@xulthekl/team-flow 0.44.0 → 0.46.0

package/scripts/lib/glaf4-evidence-export.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * glaf4-evidence-export — glaf4-dev run 证据 → surefire 兼容汇总（v2.1 §7 接口④）
+ *
+ * 零 glaf4-dev 改动：只读 glaf4-dev run 目录内部结构（有界演进，§8）。
+ * 用法：tf glaf4-evidence-export <run-dir> <output-file> [--mode <mode>] [--json]
+ *
+ * 流程（v2.1 §7）：
+ * 1. 读取 run 终局 final-result.json，仅 status=PASS（防模型手写；FAIL/BLOCKED 走 6.7 恢复路径）
+ * 2. 按模式→最终测试证据阶段映射聚合（MODE_STAGES 实证）
+ * 3. 遍历 stages/{stage}/attempts/attempt-<n>/test-result.json，只聚合每 batch 最终 GREEN（passed=true）
+ * 4. 去重（executed_classes）后再求和
+ * 5. 输出 surefire 兼容行 `Tests run: N, Failures: F, Errors: E, Skipped: S`
+ * 6. 落盘 → 用户 `tf test record <change-dir> --from <output-file>` 解析落盘 test_result
+ *
+ * total=0 边界（v2.1 §7）：tests-passing 硬拒 total≤0，聚合 total=0 时 WARN + 不落盘，
+ * 交由委托协议走 test_matrix_skipped 显式跳过（注意 skip 禁令的 TEST_BOOTSTRAP 例外）。
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * 模式 → 最终测试证据阶段映射（与 glaf4-dev scripts/runtime/stage_contract.py MODE_STAGES 对齐）
+ * 语义耦合声明（v2.1 §8.7）：stage 名（green/write-unit/write-integration/baseline-green）
+ * 不随 run.json/final-result.json 的 schema_version 钉扎，glaf4-dev 调整 stage 名则此处静默断裂，
+ * 需经接口版本契约校验面显式暴露。
+ */
+const MODE_TO_EVIDENCE_STAGES = {
+  FEATURE_TDD: ['green'],
+  BUGFIX_REGRESSION: ['green'],
+  COMPLETE_UNIT_TESTS: ['write-unit', 'green'],
+  COMPLETE_INTEGRATION_TESTS: ['write-integration', 'green'],
+  REFACTOR_PROTECTED: ['baseline-green', 'green'],
+};
+
+// 无测试委托阶段（TEST_BOOTSTRAP 零测试，skip 禁令唯一例外）
+const ZERO_TEST_MODES = ['TEST_BOOTSTRAP', 'PROJECT_INITIALIZE'];
+
+/**
+ * 解析 attempt-<n> 的数字序号
+ */
+function attemptNumber(dirName) {
+  const m = dirName.match(/^attempt-(\d+)$/);
+  return m ? parseInt(m[1], 10) : 0;
+}
+
+/**
+ * 遍历 run-dir/stages/{stage}/attempts/attempt-<n>/test-result.json
+ * 只收集 passed=true 的结果，按 stage+batch 分组取 attempt 最大的（避免 RED 尝试污染）
+ */
+function collectGreenTestResults(runDir, stages) {
+  const results = [];
+  for (const stage of stages) {
+    const stageDir = join(runDir, 'stages', stage);
+    if (!existsSync(stageDir)) continue;
+    const attemptsDir = join(stageDir, 'attempts');
+    if (!existsSync(attemptsDir)) continue;
+    const attempts = readdirSync(attemptsDir).filter(d => d.startsWith('attempt-'));
+    for (const attempt of attempts) {
+      const trPath = join(attemptsDir, attempt, 'test-result.json');
+      if (!existsSync(trPath)) continue;
+      try {
+        const tr = JSON.parse(readFileSync(trPath, 'utf-8'));
+        if (tr.passed === true) {
+          results.push({ ...tr, _attempt: attemptNumber(attempt) });
+        }
+      } catch {
+        // 损坏的 test-result.json 忽略（最终裁决由 final-result.json 承载）
+      }
+    }
+  }
+  // 按 stage_id+batch_id 分组，取每组 attempt 最大的 passed=true 结果
+  const byBatch = new Map();
+  for (const tr of results) {
+    const key = `${tr.stage_id || ''}:${tr.batch_id || ''}`;
+    const existing = byBatch.get(key);
+    if (!existing || tr._attempt > existing._attempt) byBatch.set(key, tr);
+  }
+  return [...byBatch.values()];
+}
+
+/**
+ * I2 修复（2026-08-18）：聚合 run 内 test-result.json 的 environment_error=true
+ * （final-result.schema.json 无该字段，设计 §6.7 环境分流依赖它——从 attempt 级 test-result 聚合，forward-compatible）
+ * @param {string} runDir glaf4-dev run 目录
+ * @returns {boolean}
+ */
+export function collectEnvironmentErrors(runDir) {
+  const stagesDir = join(runDir, 'stages');
+  if (!existsSync(stagesDir)) return false;
+  const stages = readdirSync(stagesDir);
+  for (const stage of stages) {
+    const attemptsDir = join(stagesDir, stage, 'attempts');
+    if (!existsSync(attemptsDir)) continue;
+    const attempts = readdirSync(attemptsDir);
+    for (const attempt of attempts) {
+      const trPath = join(attemptsDir, attempt, 'test-result.json');
+      if (!existsSync(trPath)) continue;
+      try {
+        const tr = JSON.parse(readFileSync(trPath, 'utf-8'));
+        if (tr.environment_error === true) return true;
+      } catch {
+        // 损坏忽略
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * 按 executed_classes 去重（FEATURE_TDD 多批次交付中同一测试类可能重复执行，求和虚增）
+ */
+function dedupeByClasses(results) {
+  const seen = new Set();
+  const out = [];
+  for (const tr of results) {
+    const classes = (tr.executed_classes || []).slice().sort().join('\u0000');
+    if (seen.has(classes)) continue;
+    seen.add(classes);
+    out.push(tr);
+  }
+  return out;
+}
+
+/**
+ * 聚合 glaf4-dev run 证据
+ * @param {string} runDir glaf4-dev run 目录（<root>/.glaf4-dev/runs/<run-id>）
+ * @param {string} [mode] 显式模式覆盖（默认从 final-result.json 读取）
+ * @returns {object} 聚合结果
+ */
+export function aggregateRunEvidence(runDir, mode) {
+  const finalPath = join(runDir, 'final-result.json');
+  if (!existsSync(finalPath)) {
+    return { ok: false, status: 'NO_FINAL_RESULT', error: `final-result.json 不存在: ${finalPath}` };
+  }
+
+  let finalResult;
+  try {
+    finalResult = JSON.parse(readFileSync(finalPath, 'utf-8'));
+  } catch (err) {
+    return { ok: false, status: 'CORRUPT_FINAL_RESULT', error: `final-result.json 解析失败: ${err.message}` };
+  }
+
+  if (finalResult.status !== 'PASS') {
+    // I2 修复（2026-08-18）：环境分流——final-result 无 environment_error 字段（schema 实证），
+    // 从 test-result 聚合 + final-result forward-compatible 读取。环境错误直接转降级，不浪费重试轮次（v2.1 §6.7）。
+    const environmentError = finalResult.environment_error === true
+      || collectEnvironmentErrors(runDir);
+    return {
+      ok: false,
+      status: `NOT_PASS:${finalResult.status || 'UNKNOWN'}`,
+      mode: finalResult.mode,
+      environment_error: environmentError,
+      error: environmentError
+        ? `run 终局 ${finalResult.status}（environment_error=true，环境问题如 JAVA/依赖缺失）→ 直接转降级或转人工（v2.1 §6.7 环境分流），不浪费重试轮次`
+        : `run 终局 ${finalResult.status}，证据回灌仅接受 PASS（FAIL/BLOCKED 走恢复路径）`,
+    };
+  }
+
+  const resolvedMode = mode || finalResult.mode;
+  if (ZERO_TEST_MODES.includes(resolvedMode)) {
+    return {
+      ok: false,
+      status: `ZERO_TEST_MODE:${resolvedMode}`,
+      mode: resolvedMode,
+      error: `${resolvedMode} 无测试设计合同，走 test_matrix_skipped 显式跳过（skip 禁令唯一例外）`,
+    };
+  }
+
+  const stages = MODE_TO_EVIDENCE_STAGES[resolvedMode];
+  if (!stages) {
+    return {
+      ok: false,
+      status: `UNSUPPORTED_MODE:${resolvedMode}`,
+      mode: resolvedMode,
+      error: `模式 ${resolvedMode} 无证据阶段映射（支持: ${Object.keys(MODE_TO_EVIDENCE_STAGES).join(', ')}）`,
+    };
+  }
+
+  const greenResults = dedupeByClasses(collectGreenTestResults(runDir, stages));
+
+  let testsRun = 0;
+  let testsFailed = 0;
+  let testsErrors = 0;
+  let testsSkipped = 0;
+  for (const tr of greenResults) {
+    testsRun += tr.tests_run || 0;
+    testsFailed += tr.tests_failed || 0;
+    testsErrors += tr.tests_errors || 0;
+    testsSkipped += tr.tests_skipped || 0;
+  }
+
+  if (testsRun === 0) {
+    return {
+      ok: false,
+      status: 'ZERO_TESTS',
+      mode: resolvedMode,
+      error: '聚合 total=0（无 GREEN test-result），tests-passing 硬拒 total≤0；确无测试时走 test_matrix_skipped 显式跳过',
+      aggregated: { tests_run: 0, tests_failed: 0, tests_errors: 0, tests_skipped: 0 },
+      green_results_count: greenResults.length,
+    };
+  }
+
+  return {
+    ok: true,
+    status: 'PASS',
+    mode: resolvedMode,
+    run_id: finalResult.run_id,
+    surefire_line: `Tests run: ${testsRun}, Failures: ${testsFailed}, Errors: ${testsErrors}, Skipped: ${testsSkipped}`,
+    aggregated: {
+      tests_run: testsRun,
+      tests_failed: testsFailed,
+      tests_errors: testsErrors,
+      tests_skipped: testsSkipped,
+    },
+    green_results_count: greenResults.length,
+  };
+}
+
+/**
+ * CLI entry point
+ */
+export async function run(args) {
+  const positionals = args.filter(a => !a.startsWith('--'));
+  const flags = new Set(args.filter(a => a.startsWith('--') && !a.startsWith('--mode')));
+  const modeFlagIndex = args.indexOf('--mode');
+  const mode = modeFlagIndex >= 0 ? args[modeFlagIndex + 1] : undefined;
+
+  const runDir = positionals[0];
+  const outputFile = positionals[1];
+
+  if (!runDir || !outputFile) {
+    console.error('Usage: tf glaf4-evidence-export <run-dir> <output-file> [--mode <mode>] [--json]');
+    process.exit(2);
+  }
+
+  const json = flags.has('--json');
+  const result = aggregateRunEvidence(runDir, mode);
+
+  if (!result.ok) {
+    console.error(`❌ glaf4-evidence-export: ${result.error}`);
+    if (json) console.log(JSON.stringify(result));
+    process.exit(1);
+  }
+
+  // 落盘 surefire 兼容文件，供 `tf test record --from` 解析
+  const outDir = outputFile.substring(0, outputFile.lastIndexOf('/'));
+  if (outDir && outDir !== outputFile) mkdirSync(outDir, { recursive: true });
+  writeFileSync(outputFile, `${result.surefire_line}\n`, 'utf-8');
+
+  if (json) {
+    console.log(JSON.stringify(result));
+  } else {
+    console.log(`✅ glaf4-evidence-export: ${result.surefire_line}`);
+    console.log(`   证据来源: ${result.run_id} (mode: ${result.mode}, ${result.green_results_count} 个 GREEN test-result)`);
+    console.log(`   落盘: ${outputFile} → 执行 tf test record <change-dir> --from ${outputFile}`);
+  }
+}
+
+// 直接运行（与 conventions-generator.mjs 同构）
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run(process.argv.slice(2)).catch(err => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/scripts/lib/state-loader.mjs

@@ -40,6 +40,13 @@ const BUILTIN_DEFAULTS = {
   dp_3_timestamp: null,
   dp_4_result: null,
   dp_4_timestamp: null,
+  // GLAF4 委托决策（v2.1 §6.6：dp_4_glaf4_mode 枚举标量入 state；write_set_boundary 落契约/JSON，state 只存引用 hash）
+  dp_4_glaf4_mode: null,
+  dp_4_write_set_hash: null,
+  // GLAF4 委托状态位（v2.1 §6.7：failed 时 guard 阻断 closing 直到人工重置）
+  delegation_status: null,
+  delegation_retry_count: null,
+  delegation_partial_writes: null,
   dp_5_result: null,
   dp_5_timestamp: null,
   dp_6_result: null,
@@ -150,6 +157,12 @@ export function writeState(changeDir, state) {
   lines.push(`dp_3_timestamp: ${state.dp_3_timestamp ?? 'null'}`);
   lines.push(`dp_4_result: ${state.dp_4_result ?? 'null'}`);
   lines.push(`dp_4_timestamp: ${state.dp_4_timestamp ?? 'null'}`);
+  // v2.1 §6.6：GLAF4 委托决策字段（枚举标量入 state；write_set_boundary 不落 YAML，只存引用 hash）
+  lines.push(`dp_4_glaf4_mode: ${state.dp_4_glaf4_mode ?? 'null'}`);
+  lines.push(`dp_4_write_set_hash: ${state.dp_4_write_set_hash ?? 'null'}`);
+  lines.push(`delegation_status: ${state.delegation_status ?? 'null'}`);
+  lines.push(`delegation_retry_count: ${state.delegation_retry_count ?? 'null'}`);
+  lines.push(`delegation_partial_writes: ${state.delegation_partial_writes ?? 'null'}`);
   lines.push(`dp_5_result: ${state.dp_5_result ?? 'null'}`);
   lines.push(`dp_5_timestamp: ${state.dp_5_timestamp ?? 'null'}`);
   lines.push(`dp_6_result: ${state.dp_6_result ?? 'null'}`);

package/scripts/lib/test-matrix-export.mjs

@@ -2,14 +2,20 @@
 /**
  * test-matrix-export — glaf4 test-matrix.json → team-flow test-matrix.md 格式转换
  *
- * v0.12 §46.1 定义，v0.31.0 实现为 CLI 子命令
+ * v0.12 §46.1 定义，v0.31.0 实现为 CLI 子命令；v2（glaf4-dev 集成 v2.1 §5）支持 test-matrix-vnext（schema_version "2.0"）
  * 用法：tf test-matrix-export <input.json> <output.md> [--change-id <id>] [--batch-id <id>]
  *
  * 功能：
- * - 读取 glaf4 的 test-matrix.json
+ * - 读取 glaf4 的 test-matrix.json（v1 运行级合同 或 vNext 设计合同）
  * - 保留全部 14 字段 + 包装 team_flow_context
  * - 从 test_kind 派生 test_tier（unit/integration）
  * - 输出 team-flow 格式的 test-matrix.md
+ *
+ * vNext 兼容（v2.1 §5）：
+ * - 顶层无 target → 模块名从 case.target 推导（取最后大写开头段 = 类名）
+ * - kind → work_mode 映射：TDD/REGRESSION/CHARACTERIZATION 直传，REFACTOR → TDD（原始语义记 footer）
+ * - write_targets 数组 → 每个 target 拆一行，test_file 取文件名、test_method_name 取 `#方法` 锚点
+ * - case_id 与 test-merge rewriteIndex 正则 `\S+-\S+-\S+-\d+` 兼容性 WARN（直传不阻断）
  */
 
 import { readFileSync, writeFileSync } from 'node:fs';
@@ -59,6 +65,52 @@ const TEST_KIND_TO_TIER = {
   playwright_integration: 'e2e',
 };
 
+/**
+ * kind → work_mode 映射（v2.1 §5）
+ * TDD/REGRESSION/CHARACTERIZATION 直传；REFACTOR → TDD（有损映射，原始语义记 footer）
+ */
+const KIND_TO_WORK_MODE = {
+  TDD: 'TDD',
+  REGRESSION: 'REGRESSION',
+  CHARACTERIZATION: 'CHARACTERIZATION',
+  REFACTOR: 'TDD',
+};
+
+/**
+ * test-merge rewriteIndex 的 case_id 兼容正则（test-merge.mjs rewriteIndex）
+ * case_id 形如 `xxx-yyy-zzz-123`，不匹配则 rewriteIndex 统计会漏（WARN 不阻断）
+ */
+const CASE_ID_REWRITE_INDEX_PATTERN = /^\S+-\S+-\S+-\d+$/;
+
+/**
+ * 解析 write_targets 锚点 `文件#方法`
+ * @param {string} target 如 "src/test/java/com/example/OrderServiceTest.java#testCreateOrder"
+ * @returns {{ test_file: string, test_method_name: string }}
+ */
+function parseWriteTarget(target) {
+  const [filePart, methodPart] = target.split('#');
+  return {
+    test_file: filePart ? basename(filePart) : '',
+    test_method_name: methodPart || '',
+  };
+}
+
+/**
+ * 从 case.target 推导模块名（vNext 顶层无 target）
+ * target 形如 "OrderService" | "OrderService.createOrder" | "com.example.service.OrderService.createOrder"
+ * → 取最后一个大写开头的段（类名）
+ * @param {string} target
+ * @returns {string}
+ */
+function extractModuleFromTarget(target) {
+  if (!target) return 'Unknown';
+  const segments = target.split('.');
+  for (let i = segments.length - 1; i >= 0; i--) {
+    if (/^[A-Z]/.test(segments[i])) return segments[i];
+  }
+  return segments[segments.length - 1];
+}
+
 /**
  * 从 glaf4 case 派生 test_tier
  */
@@ -96,7 +148,8 @@ function caseToRow(c) {
 }
 
 /**
- * 提取模块名（从 target 或 case_id 前缀）
+ * 提取模块名（从 target / case.target / case_id 前缀）
+ * vNext 顶层无 target，从 case.target 推导（v2.1 §5）
  */
 function extractModuleName(matrix) {
   if (matrix.target) {
@@ -104,6 +157,10 @@ function extractModuleName(matrix) {
     const parts = matrix.target.split('.');
     return parts[parts.length - 1];
   }
+  // vNext：从 case.target 推导（取最后大写开头段 = 类名）
+  if (matrix.cases?.[0]?.target) {
+    return extractModuleFromTarget(matrix.cases[0].target);
+  }
   // fallback: from first case_id
   if (matrix.cases?.[0]?.case_id) {
     const id = matrix.cases[0].case_id;
@@ -113,10 +170,71 @@ function extractModuleName(matrix) {
   return 'Unknown';
 }
 
+/**
+ * 转换单个 vNext case 为 markdown 行（write_targets 数组 → 多行拆分）
+ */
+function vnextCaseToRows(c) {
+  const tier = deriveTestTier(c.test_kind);
+  const workMode = KIND_TO_WORK_MODE[c.kind] || c.kind || 'TDD';
+  const mock = Array.isArray(c.collaborators)
+    ? c.collaborators.join(', ')
+    : (c.mock || '');
+  const targets = Array.isArray(c.write_targets) && c.write_targets.length > 0
+    ? c.write_targets
+    : [''];
+  return targets.map((t) => {
+    const { test_file, test_method_name } = parseWriteTarget(t);
+    return [
+      c.case_id || '',
+      escapeCell(c.behavior || c.display_name || ''),
+      c.design_method || '',
+      escapeCell(typeof c.input === 'object' ? JSON.stringify(c.input) : (c.input || '')),
+      escapeCell(typeof c.expected === 'object' ? JSON.stringify(c.expected) : (c.expected || '')),
+      c.test_kind || '',
+      tier,
+      escapeCell(mock),
+      workMode,
+      test_file,
+      test_method_name,
+      '', // run_command：vNext 无此字段
+    ].join(' | ');
+  });
+}
+
+/**
+ * vNext 检测：schema_version === "2.0"（test-matrix-vnext 设计合同）
+ */
+function isVnextMatrix(matrix) {
+  return matrix.schema_version === '2.0';
+}
+
+/**
+ * 接口版本契约门（v2.1 §8.3，C2 修复 2026-08-18）：
+ * schema_version 必须在 ['1.0','2.0'] 内；未定义视为 v1 兼容（glaf4 早期矩阵）。
+ * 未来版本（如 2.1/3.0）显式抛错 BLOCK，不静默按 v1 解析——防 glaf4-dev 升级后静默错接。
+ * @param {object} matrix
+ * @throws {Error} 不兼容版本
+ */
+export function validateSchemaVersion(matrix) {
+  const raw = matrix?.schema_version;
+  if (raw === undefined || raw === null) return '1.0'; // 早期矩阵无版本字段，按 v1 兼容
+  // Minor#3（复评 2026-08-18）：版本归一化——设计约定字符串 "2.0"，数字 2 或字符串 '2' 均归一为 '2.0'
+  const version = typeof raw === 'number' ? `${raw}.0` : String(raw);
+  if (version === '1' || version === '2') return `${version}.0`;
+  if (version === '1.0' || version === '2.0') return version;
+  throw new Error(
+    `不兼容的 test-matrix schema_version "${version}"（支持: 1.0 / 2.0）。`
+    + 'glaf4-dev 升级了矩阵 schema？请升级 test-matrix-export 后重试（v2.1 §8.3 接口版本契约，不静默错接）。'
+  );
+}
+
 /**
  * 转换 glaf4 matrix → team-flow markdown
+ * 支持 v1（schema_version "1.0"）与 vNext（schema_version "2.0"），结构锚点对齐（v2.1 §5）
  */
 export function convert(matrix, options = {}) {
+  const schemaVersion = validateSchemaVersion(matrix); // C2 版本门：不兼容版本 BLOCK
+  const vnext = schemaVersion === '2.0'; // 用归一化版本判断（数字 2 → '2.0' 正确走 vNext 分支）
   const moduleName = extractModuleName(matrix);
   const cases = matrix.cases || [];
 
@@ -125,7 +243,7 @@ export function convert(matrix, options = {}) {
   const integrationCases = cases.filter(c => deriveTestTier(c.test_kind) === 'integration');
   const e2eCases = cases.filter(c => deriveTestTier(c.test_kind) === 'e2e');
 
-  // 提取 complexity
+  // 提取 complexity（vNext 顶层无 target_complexity，默认 medium）
   const complexity = matrix.target_complexity || {};
   let complexityTier = 'medium';
   if (complexity.is_trivial) complexityTier = 'trivial';
@@ -133,9 +251,18 @@ export function convert(matrix, options = {}) {
     complexityTier = 'complex';
   }
 
-  // 提取 candidate ledger
+  // 提取 candidate ledger（vNext 无 source_candidate_ledger）
   const candidateLedger = matrix.source_candidate_ledger || [];
 
+  // vNext：case_id 与 test-merge rewriteIndex 正则兼容性 WARN（v2.1 §5）
+  if (vnext) {
+    for (const c of cases) {
+      if (c.case_id && !CASE_ID_REWRITE_INDEX_PATTERN.test(c.case_id)) {
+        console.warn(`⚠️  test-matrix-export: case_id "${c.case_id}" 不匹配 test-merge rewriteIndex 正则 (\\S+-\\S+-\\S+-\\d+)，复利 INDEX 统计可能漏计`);
+      }
+    }
+  }
+
   // 构建 markdown
   const lines = [];
   lines.push(`# Test Matrix — ${options.changeId || 'unknown'}`);
@@ -148,6 +275,9 @@ export function convert(matrix, options = {}) {
   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`);
+  if (vnext) {
+    lines.push(`- Schema version: 2.0 (test-matrix-vnext)`);
+  }
   lines.push('');
 
   // Candidate Coverage Ledger
@@ -162,7 +292,7 @@ export function convert(matrix, options = {}) {
     lines.push('');
   }
 
-  // Cases
+  // Cases（结构锚点 `### {module}` 必须保留，test-merge 依赖分段）
   lines.push('## Cases');
   lines.push('');
   lines.push(`### ${moduleName}`);
@@ -170,7 +300,10 @@ export function convert(matrix, options = {}) {
   lines.push('| case_id | behavior | design_method | input | expected | test_kind | test_tier | mock | work_mode | test_file | test_method_name | run_command |');
   lines.push('|---|---|---|---|---|---|---|---|---|---|---|---|');
   for (const c of cases) {
-    lines.push(`| ${caseToRow(c)} |`);
+    const rows = vnext ? vnextCaseToRows(c) : [caseToRow(c)];
+    for (const row of rows) {
+      lines.push(`| ${row} |`);
+    }
   }
   lines.push('');
 
@@ -195,7 +328,17 @@ export function convert(matrix, options = {}) {
   if (options.batchId) lines.push(`  batch_id: ${options.batchId}`);
   lines.push(`  closing_stage: test-merge`);
   if (options.ledgerRef) lines.push(`  ledger_ref: ${options.ledgerRef}`);
-  lines.push(`  source: glaf4-tests-export`);
+  lines.push(`  source: ${vnext ? 'glaf4-dev-vnext' : 'glaf4-tests-export'}`);
+  if (vnext) {
+    lines.push(`  schema_version: ${matrix.schema_version}`);
+    if (matrix.mode) lines.push(`  mode: ${matrix.mode}`);
+    if (matrix.run_id) lines.push(`  run_id: ${matrix.run_id}`);
+    // REFACTOR 原始语义记 footer（work_mode 已映射为 TDD，v2.1 §5）
+    const refactorCases = cases.filter(c => c.kind === 'REFACTOR').map(c => c.case_id);
+    if (refactorCases.length > 0) {
+      lines.push(`  refactor_kind_mapped: ${refactorCases.join(', ')}`);
+    }
+  }
   lines.push('-->');
 
   return lines.join('\n') + '\n';

package/scripts/team-flow.mjs

@@ -40,6 +40,8 @@ const COMMANDS = {
   arch:                () => import('./lib/cmd-arch.mjs'),
   'test-merge':        () => import('./lib/test-merge.mjs'),
   'test-matrix-export': () => import('./lib/test-matrix-export.mjs'),
+  'glaf4-evidence-export': () => import('./lib/glaf4-evidence-export.mjs'),
+  'glaf4-delegation': () => import('./lib/glaf4-delegation.mjs'),
   test:                () => import('./lib/test-record.mjs'),
 };
 
@@ -70,6 +72,10 @@ Commands:
                         Merge test matrix results into global docs/test-ledger/
   test-matrix-export <input.json> <output.md> [--change-id <id>]
                         Convert glaf4 test-matrix.json to team-flow test-matrix.md
+  glaf4-evidence-export <run-dir> <output-file> [--mode <mode>]
+                        Aggregate glaf4-dev run PASS evidence → surefire line (v2.1 §7; feed test record --from)
+  glaf4-delegation <sub> <dir> [--mode <m> --write-set <json> | --run-dir <run> | --delegation-mode <mode>]
+                        GLAF4 委托协议 (v2.1 §4/6.3/6.6/6.7): detect / confirm / verify-write-set / verify-tasks / record-partial / reset
   test record <dir> --from <runner-output> [--runner auto|maven-surefire|jest|pytest]
                         Record programmatic test evidence (v0.13 §50; feeds tests-passing gate)
   config [options]      Display or modify configuration

package/skills/architecture-design/SKILL.md

@@ -176,7 +176,7 @@ change 进入 closing 阶段时，由 release-archivist 调用 `tf arch-merge` C
 | 变更级（默认） | workflow-start（exploring→specifying） | 五项检查 | `changes/<name>/architecture/` 三件套 + sql/ | architecture-design 子代理 |
 | 产品级（product 模式） | workflow-orchestrator S3.5（architecture 阶段） | 8 步全系统结构级设计（无五项检查） | `docs/architecture/iterations/vN/architecture.md`（6 产物快照） | architecture-design product 模式子代理（唯一 owner） |
 
-**产品级模式执行**：按 `references/s3.5-product-architecture.md` SOP（8 步），模板用 `references/s3.5-architecture-template.md`，加载协议用 `references/s3.5-loading-protocol.md`。产出经 architecture-reviewer product 视角评审（`review_mode: product`）PASS 才进 S4。时序遵守 P1：只写快照不写全局。
+**产品级模式执行**：按 `references/s3.5-product-architecture.md` SOP（8 步），模板用 `references/s3.5-architecture-template.md`，加载协议用 `references/s3.5-loading-protocol.md`。产出经 architecture-reviewer product 视角评审（`review_mode: product`）PASS 才进 S3（2026-08-19：ARCH 上移 S3 前，原"进 S4"）。时序遵守 P1：只写快照不写全局。
 
 ### 独立调用
 

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

@@ -2,7 +2,7 @@
 
 > 产品级架构设计（architecture 阶段）产出的权威文档模板。基于 4A + DDD 方法论，覆盖 6 类产物。
 > 位置：`docs/architecture/iterations/vN/architecture.md`（预测态快照，P1：不写全局当前态）。
-> 产出后须经产品级评审门（architecture-reviewer product 视角）PASS 才进 S4。
+> 产出后须经产品级评审门（architecture-reviewer product 视角）PASS 才进 S3（2026-08-19：ARCH 上移 S3 前，原"进 S4"）。
 
 ## 文档骨架
 

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

@@ -1,6 +1,6 @@
 # S3.5 产品级架构设计 SOP（v0.35.0，v0.14 §59/§60）
 
-> architecture 阶段（S3 之后、S4 之前）的执行 SOP。产出 `docs/architecture/iterations/vN/architecture.md`（预测态快照）。
+> architecture 阶段（2026-08-19 调整：S2 之后、S3 之前——ARCH 上移，S3 计划/S4 拆分是最终任务拆分须基于架构；原" S3 之后、S4 之前"历史位置）的执行 SOP。产出 `docs/architecture/iterations/vN/architecture.md`（预测态快照）。
 > **owner**：architecture-design skill 的 **product 模式**子代理（唯一 owner，声明见 architecture-design/SKILL.md「独立调用」扩展）。
 > **时序（P1）**：只写快照不写全局；change 关闭时 arch-merge 回写实际增量；迭代收尾快照标 `archived` 退役。
 
@@ -48,7 +48,7 @@
 | A5 | 与全局基线一致性（旧项目逆向重建产物 vs 现状代码） |
 | A6 | conventions 合规 |
 
-规则：≤3 轮修复循环 + 收敛检测（连续两轮不一致项不缩小 → 转人工）；PASS 才进 S4。
+规则：≤3 轮修复循环 + 收敛检测（连续两轮不一致项不缩小 → 转人工）；PASS 才进 S3（2026-08-19：ARCH 上移 S3 前，原"进 S4"）。
 **skip 时**：architecture-reviewer 不执行，但 skip 必须物化（iterations/vN/SKIPPED 标记 + 理由）。
 
 ### 复利捕获（Step 9，v0.36.3 复利链路修复）

package/skills/contract-builder/SKILL.md

@@ -118,9 +118,9 @@ hotfix/tweak workflow 不生成 test-matrix.md（guard 豁免）；full workflow
 tf state set <change-dir> test_matrix_skipped true && tf state set <change-dir> test_matrix_skip_reason "<一句话说明>"
 ```
 
-### GLAF4 Java 路由
+### GLAF4 Java 路由（v2.1 §6 实施委托交接）
 
-当项目技术栈为 GLAF4 Java（Spring Boot / JUnit 5 / Mockito）时，提示用户是否调用 `glaf4-test:glaf4-tests` 做精细矩阵设计。用户同意后：`glaf4-tests-design` 生成 `test-matrix.json` → `glaf4-tests-validate` 校验 → `tf test-matrix-export <test-matrix.json> <change-dir>/test-matrix.md` 转换为 team-flow 格式。完整 7 步协议见 workflow-start `references/routing-rules.md`「Route to glaf4-tests」。
+当项目技术栈为 GLAF4 Java（pom.xml/build.gradle + Spring Boot/JUnit5/Mockito）时，运行时探测 glaf4-dev 插件（`detectGlaf4Delegation`）。若 `is_glaf4_java && glaf4_dev_available && delegation_mode !== 'off'`，产出 `## GLAF4 Delegation` 段（mode + write_set_boundary + 权限位），作为**实施委托交接**——GLAF4 change 的生产+测试整体委托 glaf4-dev 七模式流，build-executor 退为兜底。完整协议见 `references/glaf4-delegation.md`（§6.1-§6.7）。矩阵设计委托（glaf4-test）已统一到 glaf4-dev（v2.1 §1.3）。**GLAF4 委托 change 例外**：上方 Hotfix/Tweak 的显式 skip 豁免不适用——委托路径下 test-matrix 是审计基线，`test_matrix_skipped` 被委托协议禁止（唯一例外 TEST_BOOTSTRAP 零测试，v2.1 §6.3 skip 禁令）。
 
 ## Approval Model (DP-3)