@xulthekl/team-flow 0.34.1 → 0.36.0

package/scripts/lib/arch-parse.mjs

@@ -0,0 +1,162 @@
+// scripts/lib/arch-parse.mjs — 结构化解析 change 架构产物（v0.35.0，v0.14 §62.2）
+//
+// P2 机器管结构：从 markdown 表格 / schema SQL 提取机器可读数据，替代正则扫 markdown。
+// 背景（红队评估实证）：旧实现正则硬编码（`## 2. To-Be`、`/api/` 前缀、反引号表名）
+// 在 LLM 文档标题漂移/格式变化时静默失败（match 失配返回空串、流程继续、返回 merged:true）。
+// 本模块用通用表格解析（按 `|` split + 去反引号）与格式容错匹配，抽取失配由调用方 abort。
+
+/** 解析一行 markdown 表格为单元格数组（去反引号/去 code 包裹/trim）。非表格行返回 null。 */
+export function parseTableRow(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('|') || !trimmed.endsWith('|')) return null;
+  return trimmed
+    .slice(1, -1)
+    .split('|')
+    .map(cell => cell.trim().replace(/`/g, '').trim());
+}
+
+/**
+ * 在内容中定位某个标题（headingRe），解析其后的第一个表格为行数组。
+ * 标题匹配容错：不依赖序号/中英文（如 `/^#{2,3}\s*\d*\.?\s*(聚合注册表|Aggregate Registry)/i`）。
+ * 返回行数组（每行 = 单元格数组）；找不到标题或表格返回 []。
+ */
+export function parseTableAfter(content, headingRe) {
+  const lines = content.split('\n');
+  let i = 0;
+  for (; i < lines.length; i++) {
+    if (headingRe.test(lines[i])) break;
+  }
+  if (i >= lines.length) return [];
+  for (; i < lines.length; i++) {
+    if (lines[i].trim().startsWith('|')) break;
+  }
+  if (i >= lines.length) return [];
+  const rows = [];
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim().startsWith('|')) break;
+    if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
+    const cells = parseTableRow(line);
+    if (cells && cells.length > 0) rows.push(cells);
+  }
+  return rows;
+}
+
+/**
+ * 从 api.md 提取端点（Command/Read/Query 三段表格）。
+ * 容错：匹配路径单元格（`/xxx/{id}`）与方法单元格（GET/POST/PUT/DELETE/PATCH），
+ * 不依赖 `/api/` 前缀硬编码（企业系统可能是 /v1/、/gateway/oms/ 等）。
+ */
+export function extractEndpoints(apiMd) {
+  const endpoints = [];
+  const lines = apiMd.split('\n');
+  let currentKind = 'unknown';
+  for (const line of lines) {
+    if (/^#{2,3}\s*.*(Command|命令)/i.test(line)) currentKind = 'Command';
+    else if (/^#{2,3}\s*.*(Read|读取)/i.test(line)) currentKind = 'Read';
+    else if (/^#{2,3}\s*.*(Query|查询)/i.test(line)) currentKind = 'Query';
+    if (!line.trim().startsWith('|')) continue;
+    const cells = parseTableRow(line);
+    if (!cells || cells.length === 0) continue;
+    const pathCell = cells.find(c => /^\/[\w\-/{}.]+$/.test(c));
+    if (!pathCell) continue;
+    const methodCell = cells.find(c => /^(GET|POST|PUT|DELETE|PATCH)$/i.test(c));
+    // kind：章节标题优先；若无章节标题（如 API-INDEX 生成格式），从表格分流列取
+    const kindCell = cells.find(c => /^(Command|Read|Query)$/i.test(c));
+    const kind = currentKind !== 'unknown' ? currentKind : (kindCell || 'unknown');
+    endpoints.push({ path: pathCell, method: methodCell ? methodCell.toUpperCase() : '', kind });
+  }
+  return endpoints;
+}
+
+/**
+ * 从 architecture.md 提取聚合清单。聚合 id 格式 `context:Aggregate`。
+ * 兼容两种模板：
+ * - 产品级「聚合注册表」：`| 聚合ID | 上下文 | 根实体 | ... |`（列1=上下文，列2=根，列5=不变量）
+ * - change 级「To-Be 增量设计 §2.1 聚合变更」：`| 聚合名称 | 操作 | 聚合根 | ... | 所属 BC |`（列1=操作，列5=所属 BC）
+ */
+export function extractAggregates(archMd) {
+  let rows = parseTableAfter(archMd, /^#{2,3}\s*\d*\.?\s*(聚合注册表|Aggregate Registry)/i);
+  if (rows.length === 0) {
+    rows = parseTableAfter(archMd, /^#{3,4}\s*\d*\.?\s*(聚合变更|Aggregate Changes)/i);
+  }
+  if (rows.length === 0) {
+    rows = parseTableAfter(archMd, /^#{2,3}\s*\d*\.?\s*To-Be/i);
+  }
+  const aggregates = [];
+  for (const row of rows) {
+    const id = row[0]?.trim();
+    if (!id || id === '聚合ID' || id === '聚合名称' || id === 'Aggregate') continue;
+    if (!/^[\w]+:[\w]+$/.test(id)) continue;
+    const col1 = row[1]?.trim() || '';
+    const isChange = /^(新增|修改|New|Update)/i.test(col1);
+    // source：产品级全局格式（buildCurrentStateSection 生成）列3=来源 changeName；change 级无来源列 → ''
+    const source = /^change:/.test(row[3]?.trim() || '') ? row[3].trim() : '';
+    aggregates.push({
+      id,
+      context: isChange ? (row[5]?.trim() || '') : col1,
+      root: row[2]?.trim() || '',
+      invariants: isChange ? '' : (row[5]?.trim() || ''),
+      source,
+    });
+  }
+  return aggregates;
+}
+
+/** 从 schema-baseline.sql 提取 CREATE TABLE 表名（容错：IF NOT EXISTS / 反引号 / schema 前缀）。 */
+export function extractTablesFromSql(sql) {
+  const tables = [];
+  const re = /CREATE\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?\s+`?([\w.]+)`?\s*(?:\(|;)/gi;
+  let m;
+  while ((m = re.exec(sql))) {
+    tables.push(m[1].replace(/`/g, ''));
+  }
+  return [...new Set(tables)];
+}
+
+/**
+ * 从演进日志段提取条目。返回 `{ key, content }[]`，key 用 changeName 唯一锚
+ *（`### change:<name>` 或 `### <name>`），替代按版本号去重（不同 change 可能同版本号）。
+ */
+export function extractEvolutionLogEntries(archMd, changeName) {
+  const logStart = archMd.search(/^#{2,3}\s*\d*\.?\s*(演进日志|Evolution Log)/m);
+  if (logStart < 0) return [];
+  const logSection = archMd.slice(logStart);
+  const entries = [];
+  const blockRe = /(###\s+.+)([\s\S]*?)(?=###\s|##\s|\n#\s|$)/g;
+  let m;
+  while ((m = blockRe.exec(logSection))) {
+    const title = m[1].trim();
+    const body = m[2].trim();
+    if (!title || !body) continue;
+    entries.push({ key: changeName, title, body });
+  }
+  return entries;
+}
+
+/** 从 database.md 的 Schema 变更详情段（§3）提取受影响的表。 */
+export function extractTablesFromDatabaseMd(dbMd) {
+  const tables = new Set();
+  // 匹配表格行中的 CREATE/ALTER TABLE 操作列
+  const re = /(?:CREATE|ALTER)\s+TABLE(?:\s+IF\s+NOT\s+EXISTS)?\s+`?([\w.]+)`?/gi;
+  let m;
+  while ((m = re.exec(dbMd))) {
+    tables.add(m[1].replace(/`/g, ''));
+  }
+  // 兜底：匹配形如 `t_xxx` 的表名行
+  const tableRe = /\b(t_[a-z_0-9]+)\b/g;
+  while ((m = tableRe.exec(dbMd))) tables.add(m[1]);
+  return [...tables];
+}
+
+/** 从 markdown 中提取所有 frontmatter 字段（简单正则，与 state-loader 兼容）。 */
+export function readFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const fm = {};
+  for (const line of match[1].split('\n')) {
+    const m = line.match(/^(\w+):\s*(.*)$/);
+    if (m) fm[m[1]] = m[2].trim();
+  }
+  return fm;
+}

package/scripts/lib/cmd-arch.mjs

@@ -0,0 +1,84 @@
+// scripts/lib/cmd-arch.mjs — tf arch init/show：项目级架构基线打戳（v0.35.0，v0.14 §59.4/§63.1）
+//
+// arch_baseline 完全复刻 v0.13 §48.1 schema_version 防污染模式：
+// 仅 `tf arch init` 打戳（项目级 .team-flow/arch-state.json），缺失 = 存量信号。
+// 防污染：已打戳则拒绝重复 init（不覆盖）；rebuild/doctor/set 一律不追加。
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+const ARCH_STATE_FILE = '.team-flow/arch-state.json';
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    options: {
+      'project-root': { type: 'string' },
+      mode: { type: 'string', default: 'reconstruction' },
+      'baseline-ref': { type: 'string', default: 'prd/vN/' },
+    },
+    allowPositionals: true,
+  });
+
+  const sub = positionals[0];
+  if (sub === 'init') return init(values);
+  if (sub === 'show') return show(values);
+  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show');
+  process.exit(2);
+}
+
+function findRoot(rootOpt) {
+  if (rootOpt) return path.resolve(rootOpt);
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.team-flow'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return dir;
+}
+
+function readState(root) {
+  const target = path.join(root, ARCH_STATE_FILE);
+  if (!fs.existsSync(target)) return null;
+  try { return JSON.parse(fs.readFileSync(target, 'utf-8')); }
+  catch { return null; }
+}
+
+function init(values) {
+  const root = findRoot(values['project-root']);
+  const target = path.join(root, ARCH_STATE_FILE);
+  const mode = values.mode === 'design' ? 'design' : 'reconstruction';
+
+  const existing = readState(root);
+  if (existing?.arch_baseline) {
+    console.error(
+      `arch-state.json already established (arch_baseline=${existing.arch_baseline}, mode=${existing.mode})`
+      + ' — 防污染规则：不重复打戳。如需重建，先手工处理旧标记。'
+    );
+    process.exit(1);
+  }
+
+  const state = {
+    arch_baseline: 'v0',
+    established_at: new Date().toISOString(),
+    mode,
+    snapshot_root: 'iterations/',
+    baseline_prd_ref: values['baseline-ref'],
+  };
+
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, JSON.stringify(state, null, 2) + '\n');
+  console.log(`arch-state.json written: ${target}`);
+  console.log(JSON.stringify(state, null, 2));
+  console.log('项目架构基线已打戳，进入 design 模式。重建快照位于 docs/architecture/iterations/v0/。');
+}
+
+function show(values) {
+  const root = findRoot(values['project-root']);
+  const state = readState(root);
+  if (!state) {
+    console.log('arch_baseline: <unset>（存量/未建立，S3.5 reconstruction pending）');
+    return;
+  }
+  console.log(JSON.stringify(state, null, 2));
+}

package/scripts/lib/cmd-deisolate.mjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+// scripts/lib/cmd-deisolate.mjs — worktree deisolation (v0.35.0)
+//
+// 检测 change 的 worktree 状态，输出合并建议或执行合并/清理。
+// 与 ensure-branch.mjs（创建）对称，补全 worktree 生命周期。
+//
+// Usage:
+//   tf deisolate <change-dir>                  # dry-run: 输出状态报告
+//   tf deisolate <change-dir> --merge          # 合并 worktree 分支回 master
+//   tf deisolate <change-dir> --merge --clean  # 合并后删除 worktree + 分支
+//   tf deisolate <change-dir> --clean          # 仅删除 worktree（不合并）
+//
+// 布局识别（对称 ensure-branch.mjs）：
+//   Case A 多仓库工作区：<root>/.worktrees/<change>/<repo>/ 存在
+//   Case B 单仓库：<change-dir> 同级 ../<repo>-<change-name> 存在
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    options: {
+      merge: { type: 'boolean', default: false },
+      clean: { type: 'boolean', default: false },
+      'project-root': { type: 'string' },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  if (values.help || positionals.length === 0) {
+    printHelp();
+    return;
+  }
+
+  const changeDir = resolve(positionals[0]);
+  const changeName = basename(changeDir);
+
+  // 检测布局
+  const workspaceRoot = detectWorkspaceRoot(changeDir);
+  const caseA = workspaceRoot ? detectCaseA(workspaceRoot, changeName) : null;
+  const caseB = detectCaseB(changeDir, changeName);
+
+  if (!caseA && !caseB) {
+    const msg = `No worktrees found for change '${changeName}'.`;
+    if (values.json) {
+      console.log(JSON.stringify({ found: false, message: msg }));
+    } else {
+      console.log(`✅ ${msg}`);
+    }
+    return;
+  }
+
+  const repos = caseA || caseB;
+  const results = [];
+
+  for (const repo of repos) {
+    const result = processRepo(repo, values);
+    results.push(result);
+  }
+
+  if (values.json) {
+    console.log(JSON.stringify({ found: true, repos: results }, null, 2));
+  } else {
+    printReport(results, values);
+  }
+}
+
+function detectWorkspaceRoot(absChangeDir) {
+  const parent = dirname(absChangeDir);
+  if (basename(parent) !== 'changes') return null;
+  return dirname(parent);
+}
+
+// Case A: <root>/.worktrees/<change>/<repo>/
+function detectCaseA(root, changeName) {
+  const changeWorktreeDir = join(root, '.worktrees', changeName);
+  if (!existsSync(changeWorktreeDir)) return null;
+
+  let entries;
+  try {
+    entries = readdirSync(changeWorktreeDir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const repos = entries
+    .filter(e => e.isDirectory() && existsSync(join(changeWorktreeDir, e.name, '.git')))
+    .map(e => ({
+      name: e.name,
+      worktreePath: join(changeWorktreeDir, e.name),
+      repoPath: join(root, e.name),
+      layout: 'A',
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  return repos.length > 0 ? repos : null;
+}
+
+// Case B: ../<repo>-<change-name>
+function detectCaseB(changeDir, changeName) {
+  const parentDir = dirname(changeDir);
+  const repoName = basename(changeDir) || 'repo';
+  // 旧 ensure-branch 行为：worktree 在 ../<repo>-<name>
+  // 分支名经过 sanitize，这里用 changeName 作为近似匹配
+  const candidates = [
+    join(parentDir, `${repoName}-${changeName}`),
+    join(parentDir, `${repoName}-${basename(changeDir)}`),
+  ];
+
+  for (const wtPath of candidates) {
+    if (existsSync(join(wtPath, '.git'))) {
+      return [{
+        name: repoName,
+        worktreePath: wtPath,
+        repoPath: changeDir,
+        layout: 'B',
+      }];
+    }
+  }
+  return null;
+}
+
+function processRepo(repo, values) {
+  const result = { name: repo.name, worktreePath: repo.worktreePath, layout: repo.layout };
+
+  // 获取 worktree 分支名
+  let branch = '';
+  try {
+    branch = (execFileSync('git', ['branch', '--show-current'], {
+      encoding: 'utf-8', cwd: repo.worktreePath, stdio: ['ignore', 'pipe', 'pipe'],
+    }) || '').trim();
+  } catch {
+    result.status = 'error';
+    result.message = 'Could not determine worktree branch';
+    return result;
+  }
+  result.branch = branch;
+
+  // 获取相对 master 的 diff
+  const masterBranch = detectMasterBranch(repo.repoPath);
+  try {
+    const ahead = (execFileSync('git', ['rev-list', '--count', `${masterBranch}..${branch}`], {
+      encoding: 'utf-8', cwd: repo.worktreePath, stdio: ['ignore', 'pipe', 'pipe'],
+    }) || '0').trim();
+    const behind = (execFileSync('git', ['rev-list', '--count', `${branch}..${masterBranch}`], {
+      encoding: 'utf-8', cwd: repo.worktreePath, stdio: ['ignore', 'pipe', 'pipe'],
+    }) || '0').trim();
+    result.ahead = parseInt(ahead, 10);
+    result.behind = parseInt(behind, 10);
+  } catch {
+    result.ahead = '?';
+    result.behind = '?';
+  }
+
+  // 检查未提交改动
+  try {
+    const status = execFileSync('git', ['status', '--porcelain'], {
+      encoding: 'utf-8', cwd: repo.worktreePath, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    result.dirty = status.trim().length > 0;
+  } catch {
+    result.dirty = '?';
+  }
+
+  // 操作
+  if (values.merge) {
+    result.merge = mergeBranch(repo, branch, masterBranch);
+  }
+  if (values.clean) {
+    result.clean = cleanWorktree(repo, branch);
+  }
+
+  result.status = 'ok';
+  return result;
+}
+
+function detectMasterBranch(repoPath) {
+  try {
+    const branch = (execFileSync('git', ['branch', '--show-current'], {
+      encoding: 'utf-8', cwd: repoPath, stdio: ['ignore', 'pipe', 'pipe'],
+    }) || '').trim();
+    if (branch) return branch;
+  } catch { /* ignore */ }
+  // fallback: try master, then main
+  for (const candidate of ['master', 'main']) {
+    try {
+      execFileSync('git', ['rev-parse', `refs/heads/${candidate}`], {
+        encoding: 'utf-8', cwd: repoPath, stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      return candidate;
+    } catch { /* continue */ }
+  }
+  return 'master';
+}
+
+function mergeBranch(repo, branch, masterBranch) {
+  try {
+    const output = execFileSync('git', ['merge', branch, '--no-edit'], {
+      encoding: 'utf-8', cwd: repo.repoPath, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { success: true, message: output.trim() };
+  } catch (e) {
+    return { success: false, message: (e.stderr || e.stdout || e.message || '').toString().trim() };
+  }
+}
+
+function cleanWorktree(repo, branch) {
+  const result = { worktreeRemoved: false, branchDeleted: false, errors: [] };
+
+  // Remove worktree
+  try {
+    execFileSync('git', ['worktree', 'remove', repo.worktreePath, '--force'], {
+      encoding: 'utf-8', cwd: repo.repoPath, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    result.worktreeRemoved = true;
+  } catch (e) {
+    result.errors.push(`worktree remove: ${(e.stderr || e.message || '').toString().trim()}`);
+    // Fallback: rm -rf
+    try {
+      rmSync(repo.worktreePath, { recursive: true, force: true });
+      result.worktreeRemoved = true;
+    } catch (e2) {
+      result.errors.push(`rm fallback: ${e2.message}`);
+    }
+  }
+
+  // Delete branch (skip if merged)
+  try {
+    execFileSync('git', ['branch', '-d', branch], {
+      encoding: 'utf-8', cwd: repo.repoPath, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    result.branchDeleted = true;
+  } catch {
+    // Branch not merged — use -D only if --force equivalent
+    try {
+      execFileSync('git', ['branch', '-D', branch], {
+        encoding: 'utf-8', cwd: repo.repoPath, stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      result.branchDeleted = true;
+    } catch (e) {
+      result.errors.push(`branch delete: ${(e.stderr || e.message || '').toString().trim()}`);
+    }
+  }
+
+  return result;
+}
+
+function printReport(results, values) {
+  console.log(`\n📦 Worktree Deisolation Report\n`);
+
+  for (const r of results) {
+    console.log(`  Repo: ${r.name} (${r.layout === 'A' ? 'multi-repo' : 'single-repo'})`);
+    console.log(`    Branch: ${r.branch || 'unknown'}`);
+    console.log(`    Worktree: ${r.worktreePath}`);
+    if (r.ahead !== undefined) {
+      console.log(`    Ahead of master: ${r.ahead} commit(s)`);
+      console.log(`    Behind master: ${r.behind} commit(s)`);
+    }
+    console.log(`    Uncommitted changes: ${r.dirty === true ? '⚠️  YES' : r.dirty === false ? 'no' : 'unknown'}`);
+
+    if (r.merge) {
+      console.log(`    Merge: ${r.merge.success ? '✅ ' + r.merge.message : '❌ ' + r.merge.message}`);
+    }
+    if (r.clean) {
+      console.log(`    Worktree removed: ${r.clean.worktreeRemoved ? '✅' : '❌'}`);
+      console.log(`    Branch deleted: ${r.clean.branchDeleted ? '✅' : '❌'}`);
+      if (r.clean.errors.length > 0) {
+        console.log(`    Clean errors: ${r.clean.errors.join('; ')}`);
+      }
+    }
+    console.log();
+  }
+
+  if (!values.merge && !values.clean) {
+    console.log(`  To merge: tf deisolate <change-dir> --merge`);
+    console.log(`  To clean: tf deisolate <change-dir> --merge --clean`);
+  }
+}
+
+function printHelp() {
+  console.log(`Usage:
+  tf deisolate <change-dir>                    # dry-run: show worktree status
+  tf deisolate <change-dir> --merge             # merge worktree branch back to master
+  tf deisolate <change-dir> --merge --clean     # merge + remove worktree + delete branch
+  tf deisolate <change-dir> --clean             # remove worktree only (no merge)
+  tf deisolate <change-dir> --json              # JSON output`);
+}

package/scripts/lib/cmd-execution.mjs

@@ -1,5 +1,5 @@
 import { parseArgs } from 'node:util';
-import { createPlan, describeWaves, EXECUTION_MODES, readPlan, recordReview, validatePlan, writePlan } from './execution-plan.mjs';
+import { createPlan, describeWaves, EXECUTION_MODES, readPlan, recordReview, refreshPlanHash, validatePlan, writePlan } from './execution-plan.mjs';
 import {
   createRecommendationReceipt,
   readCurrentRecommendationReceipt,
@@ -7,7 +7,7 @@ import {
 } from './execution-recommendation.mjs';
 import { readState, writeState } from './state-loader.mjs';
 
-const SUBCOMMANDS = ['recommend', 'plan', 'show', 'revise', 'review'];
+const SUBCOMMANDS = ['recommend', 'plan', 'show', 'revise', 'review', 'refresh-hash'];
 
 export async function run(args) {
   const { positionals, values } = parseArgs({
@@ -52,6 +52,8 @@ export async function run(args) {
       return createAndPrintPlan(changeDir, values, true);
     case 'review':
       return recordAndPrintReview(changeDir, values);
+    case 'refresh-hash':
+      return refreshHash(changeDir, values.json);
   }
 }
 
@@ -203,6 +205,16 @@ function parseTestsStats(values) {
   return parsed;
 }
 
+function refreshHash(changeDir, json) {
+  const result = refreshPlanHash(changeDir);
+  if (!result) {
+    print(json, { refreshed: false }, 'Artifacts hash is already up to date.');
+    return;
+  }
+  print(json, { refreshed: true, artifacts_hash: result.artifacts_hash, contract_hash: result.contract_hash },
+    `Refreshed artifacts hash: ${result.artifacts_hash?.slice(0, 12)}…`);
+}
+
 function requireSafeReason(reason) {
   if (/[\p{Cc}\p{Zl}\p{Zp}]/u.test(reason)) {
     throw new Error('--reason must not contain control characters or line separators');
@@ -225,5 +237,6 @@ function printHelp() {
   tf execution plan <dir> --mode <mode> --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
   tf execution show <dir> [--json]
   tf execution revise <dir> --mode sdd --confirm --reason <text> --wave <id>:<strategy>:<task,...>[:<depends-on,...>] [--acknowledge-recommendation]
-  tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail [--tests-total N --tests-passed N --tests-failed N]`);
+  tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail [--tests-total N --tests-passed N --tests-failed N]
+  tf execution refresh-hash <dir> [--json]   # refresh artifacts/contract hash without bumping revision`);
 }

package/scripts/lib/execution-plan.mjs

@@ -53,9 +53,17 @@ export function writePlan(changeDir, plan) {
   mkdirSync(paths.root, { recursive: true });
   const previousPlan = readPlan(changeDir);
   if (previousPlan && (previousPlan.revision !== plan.revision || previousPlan.hash !== plan.hash)) {
-    // Review evidence is scoped to exactly one plan revision. Removing it on
-    // revision prevents an old wave ID from satisfying a changed plan.
-    rmSync(paths.reviews, { recursive: true, force: true });
+    // v0.35.0: Review receipts are RETAINED across revisions — readCurrentReview
+    // validates plan_hash/plan_revision matching, so stale receipts are
+    // automatically invalidated without losing evidence (base/head/report SHA).
+    // This prevents legitimate artifact updates (e.g., design.md 横展结论) from
+    // causing cascading receipt loss. See workflow-feedback 20260805.
+    //
+    // Recommendation receipt is revision-scoped and must be cleaned:
+    const recommendationFile = paths.executionRecommendation;
+    if (recommendationFile && existsSync(recommendationFile)) {
+      rmSync(recommendationFile, { force: true });
+    }
   }
   atomicWrite(paths.executionPlan, `${JSON.stringify(plan, null, 2)}\n`);
   writeExecutionPlanSummary(changeDir, plan);
@@ -76,10 +84,16 @@ export function validatePlan(changeDir, plan) {
     failures.push('execution plan mode does not match state');
   }
   if (plan?.artifacts_hash !== computeArtifactsHash(changeDir)) {
-    failures.push('execution plan is stale: artifacts hash mismatch');
+    const actual = computeArtifactsHash(changeDir);
+    const planPrefix = plan?.artifacts_hash?.slice(0, 12) ?? 'null';
+    const actualPrefix = actual?.slice(0, 12) ?? 'null';
+    failures.push(`execution plan is stale: artifacts hash mismatch (plan: ${planPrefix}…, current: ${actualPrefix}…)`);
   }
   if (plan?.contract_hash !== computeContractHash(changeDir)) {
-    failures.push('execution plan is stale: contract hash mismatch');
+    const actual = computeContractHash(changeDir);
+    const planPrefix = plan?.contract_hash?.slice(0, 12) ?? 'null';
+    const actualPrefix = actual?.slice(0, 12) ?? 'null';
+    failures.push(`execution plan is stale: contract hash mismatch (plan: ${planPrefix}…, current: ${actualPrefix}…)`);
   }
   if (plan?.workflow !== state.workflow) {
     failures.push('execution plan workflow does not match state');
@@ -442,6 +456,24 @@ function hashPlan(plan) {
   return `sha256:${createHash('sha256').update(stableJson(content)).digest('hex')}`;
 }
 
+/**
+ * v0.35.0: Refresh plan's artifacts_hash and contract_hash without bumping revision.
+ * Returns the updated plan (already persisted via writePlan), or null if no change needed.
+ */
+export function refreshPlanHash(changeDir) {
+  const plan = readPlan(changeDir);
+  if (!plan) return null;
+  const newArtifactsHash = computeArtifactsHash(changeDir);
+  const newContractHash = computeContractHash(changeDir);
+  if (plan.artifacts_hash === newArtifactsHash && plan.contract_hash === newContractHash) {
+    return null; // no change needed
+  }
+  plan.artifacts_hash = newArtifactsHash;
+  plan.contract_hash = newContractHash;
+  plan.hash = hashPlan(plan);
+  return writePlan(changeDir, plan);
+}
+
 function tryHashPlan(plan) {
   if (!isObject(plan)) return null;
   try {

package/scripts/lib/test-merge.mjs

@@ -534,7 +534,10 @@ async function main(argv, projectRoot) {
   console.log(`\n🎉 test-merge complete for ${changeName}`);
 }
 
-main().catch(err => {
-  console.error('test-merge error:', err.message);
-  process.exit(1);
-});
+// 直接运行（v0.35.0 修复：main() 无参自调用崩溃 → 调用 run() 走正确参数解析）
+if (import.meta.url === `file://${process.argv[1]}`) {
+  run(process.argv.slice(2)).catch(err => {
+    console.error('test-merge error:', err.message);
+    process.exit(1);
+  });
+}