@xulthekl/team-flow 0.51.1 → 0.53.0

package/scripts/lib/cmd-sync.mjs

@@ -1,7 +1,20 @@
 // tf sync <change-dir> — merge delta specs into main specs with conflict detection
+//
+// v0.24 §96（触发来源：workflow-feedback 20260910-093040，P1）：修复前为纯文件拷贝——
+// 对「主基已存在」的 capability 整体覆盖，静默删除前序 change 交付的 Requirement
+// （C3 覆盖 C2 主基，git diff --numstat = 168/60）。现在按 spec-merger SKILL.md 定义的
+// 语义合并执行：
+//   - 主基不存在（capability 首次交付）→ 拷贝（原行为）
+//   - 主基存在                        → spec-merge.mergeMainSpec（ADDED/MODIFIED/REMOVED/RENAMED）
+//   - delta 无操作段落                → clean skip（不写、不报错）
+// 多 capability 原子性：全部在内存完成，全部成功才写盘；任一失败不写任何文件、退出非 0。
+// 全部成功后写 spec_merged: true（并入 workflow-feedback 20260910-002000：此前唯一写入
+// 路径是人工 `tf state set`，导致 specs-merged guard 恒 FAIL）。
 import { readFileSync, readdirSync, writeFileSync, existsSync, statSync, mkdirSync } from 'node:fs';
-import path, { join, basename } from 'node:path';
+import path, { join, basename, dirname } from 'node:path';
 import { validateSpecPathLayout } from './spec-paths.mjs';
+import { mergeMainSpec, deltaHasOperations } from './spec-merge.mjs';
+import { updateField, readState } from './state-loader.mjs';
 
 function toPosix(value) {
   return value.replace(/\\/g, '/');
@@ -29,6 +42,13 @@ export async function run(args) {
     process.exit(2);
   }
 
+  // v0.24 §101.3：abandoned 检查上浮到命令层（原仅 spec-merger SKILL.md 的 Guard 约束）。
+  // 技能层约束无法机械保证；命令是唯一合并通道后，废弃 change 的 delta 不得合并进主基。
+  if (readState(changeDir).state === 'abandoned') {
+    console.error('❌ Abandoned change cannot be synced — delta specs are preserved for reference but must not be merged.');
+    process.exit(1);
+  }
+
   const { Validator } = await import('../../dist/index.js');
   const validator = new Validator();
 
@@ -61,14 +81,13 @@ export async function run(args) {
       console.log('⚠️  Sync conflicts detected:\n');
       for (const conflict of conflictReport.conflicts) {
         console.log(`  Requirement: "${conflict.requirement}"`);
-        console.log(`  Modified by: ${conflict.changes.join(', ')}\n`);
+        console.log(`    Modified by: ${conflict.changes.join(', ')}\n`);
       }
       console.log('Resolve conflicts before syncing. Consider syncing changes one at a time.');
       process.exit(1);
     }
   }
 
-  // Perform sync: copy delta specs to main specs/
   const changeSpecsDir = join(changeDir, 'specs');
   const mainSpecsDir = join(process.cwd(), 'specs');
   const changeName = basename(changeDir);
@@ -78,25 +97,62 @@ export async function run(args) {
     process.exit(1);
   }
 
-  if (!existsSync(mainSpecsDir)) {
-    mkdirSync(mainSpecsDir, { recursive: true });
+  // 计算阶段（内存）：任一 capability 失败即整体中止，不写任何文件（fail-closed）
+  const plan = [];
+  try {
+    for (const specFile of layout.specFiles) {
+      const capabilityDir = deriveCapabilityDir(changeSpecsDir, specFile);
+      const targetPath = join(mainSpecsDir, capabilityDir, 'spec.md');
+      const deltaContent = readFileSync(specFile, 'utf-8');
+
+      if (!existsSync(targetPath)) {
+        plan.push({ capabilityDir, targetPath, content: deltaContent, mode: 'created' });
+        continue;
+      }
+      if (!(await deltaHasOperations(deltaContent))) {
+        plan.push({ capabilityDir, targetPath, content: null, mode: 'no-ops' });
+        continue;
+      }
+      const mainContent = readFileSync(targetPath, 'utf-8');
+      const { content, report } = await mergeMainSpec(mainContent, deltaContent, changeName);
+      plan.push({ capabilityDir, targetPath, content, mode: 'merged', report });
+    }
+  } catch (e) {
+    console.error(`\n❌ Sync aborted（未写入任何文件）：${e.message}`);
+    process.exit(1);
   }
 
-  let synced = 0;
-
-  for (const specFile of layout.specFiles) {
-    const capabilityDir = deriveCapabilityDir(changeSpecsDir, specFile);
-    const targetDir = join(mainSpecsDir, capabilityDir);
+  // 应用阶段：全部成功后才写盘
+  for (const item of plan) {
+    if (item.content === null) continue;
+    mkdirSync(dirname(item.targetPath), { recursive: true });
+    writeFileSync(item.targetPath, item.content);
+  }
 
-    if (!existsSync(targetDir)) {
-      mkdirSync(targetDir, { recursive: true });
+  for (const item of plan) {
+    const rel = `specs/${item.capabilityDir}/spec.md`;
+    if (item.mode === 'created') {
+      console.log(`  📋 Created: ${rel}`);
+    } else if (item.mode === 'no-ops') {
+      // 用告警而非普通信息：无操作段落也可能是 delta 段落标题拼写错误（畸形输入），
+      // 静默跳过会掩盖真实缺口（v0.24 §101.3）。
+      console.warn(`  ⚠️  No delta operations found: ${rel} — 若该 capability 本应有变更，请检查 delta 的段落标题（## ADDED/MODIFIED/REMOVED/RENAMED Requirements）是否拼写正确`);
+    } else {
+      const r = item.report;
+      console.log(
+        `  📋 Merged: ${rel}  (ADDED ${r.added} / MODIFIED ${r.modified} / REMOVED ${r.removed}`
+        + ` / RENAMED ${r.renamed} / skipped ${r.skipped})`,
+      );
     }
+  }
 
-    const content = readFileSync(specFile, 'utf-8');
-    writeFileSync(join(targetDir, 'spec.md'), content);
-    console.log(`  📋 Synced: specs/${capabilityDir}/spec.md`);
-    synced++;
+  // spec_merged 状态位：closing 前 specs-merged guard 依此判定（v0.24 §96.3.3）
+  if (existsSync(join(changeDir, '.team-flow.yaml'))) {
+    updateField(changeDir, 'spec_merged', true);
+  } else {
+    console.warn('  [WARN] 未找到 .team-flow.yaml，spec_merged 未记录（guard 仍会要求该状态位，请手工设置）');
   }
 
-  console.log(`\n✅ Synced ${synced} spec(s) from ${changeName} to specs/`);
+  const written = plan.filter(i => i.content !== null).length;
+  console.log(`\n✅ Synced ${written} spec(s) from ${changeName} to specs/`);
 }

package/scripts/lib/git-utils.mjs

@@ -230,6 +230,9 @@ function resolveDeclaredRepo(workspaceRoot, key, value) {
   return null;
 }
 
+/** porcelain v1 行首格式：XY + 一个空格（X/Y ∈ [ MADRCUT?!]；未暂存修改时 X 位是空格）。 */
+const PORCELAIN_LINE_RE = /^[ MADRCUT?!]{2} /;
+
 /**
  * 解析 `git status --porcelain` 输出为路径数组（v0.23 §93.3.1）。
  *
@@ -237,12 +240,26 @@ function resolveDeclaredRepo(workspaceRoot, key, value) {
  * `^\S+\s+` 剥离（该正则会漏掉 ` M path`，正是 v0.51.0 前 arch-merge 误报的根因）。
  * 以 `line.slice(3)` 按固定宽度切片，并还原引号包裹与转义空格。
  *
+ * v0.24 §98.3.2（第二道防线）：porcelain 是**固定宽度**格式，行首空格是格式的一部分。
+ * 若上游对输出做过 trim 或其它清洗（如 v0.52.0 前 cmd-publish 的 `.trim()`），
+ * `slice(3)` 会切掉路径首字符（`changes/…` → `hanges/…`）并**静默产出错误路径**。
+ * 因此对每行做形态断言，不匹配即抛错——损坏的输入无法产出可信路径，fail-loud 优于静默误报。
+ *
  * @param {string} output git status --porcelain 的原始输出
  * @returns {string[]} 仓库相对路径
+ * @throws {Error} 输入行不符合 porcelain 形态（提示上游可能清洗过输出）
  */
 export function parsePorcelainPaths(output) {
   return String(output || '')
     .split('\n')
     .filter(Boolean)
-    .map(line => line.slice(3).replace(/^"|"$/g, '').replace(/\\ /g, ' '));
+    .map(line => {
+      if (!PORCELAIN_LINE_RE.test(line)) {
+        throw new Error(
+          `parsePorcelainPaths: malformed porcelain line (input may have been trimmed/normalized `
+          + `upstream — porcelain's fixed-width prefix must be preserved): ${JSON.stringify(line)}`,
+        );
+      }
+      return line.slice(3).replace(/^"|"$/g, '').replace(/\\ /g, ' ');
+    });
 }

package/scripts/lib/prototype-sync.mjs

@@ -11,7 +11,8 @@
  * 3. 若涉及设计系统迭代（新组件/token/anti-pattern），合并进 prototype/design-system.md
  * 4. 输出合并报告
  *
- * 回写顺序：arch-merge → prototype-sync（同一 change closing 内，顺序提交）
+ * 回写顺序：arch-merge → state transition closing → prototype-sync → test-merge → compound promotion
+ * （同一 change closing 内顺序执行；状态转换位次由 v0.53.0 §110 B' 时序前移确定）
  */
 
 import { readFileSync, writeFileSync, existsSync, cpSync, mkdirSync } from 'node:fs';

package/scripts/lib/spec-merge.mjs

@@ -0,0 +1,315 @@
+// scripts/lib/spec-merge.mjs — `tf sync` 的 delta → 主基语义合并器（v0.24 §96）
+//
+// 设计权威：设计增强方案 v0.24 §96.3（工作区级文档，插件包内不含）
+// 触发来源：workflow-feedback 20260910-093040（P1）——修复前 `tf sync` 是纯文件拷贝，
+// 对「主基已存在」的 capability 会整体覆盖，静默删除前序 change 交付的 Requirement。
+//
+// 设计要点：
+// 1. **纯文本合并**（无 I/O 副作用）：输入主基 + delta 内容，输出合并结果与操作报告；
+//    写盘由调用方（cmd-sync）统一执行，保证多 capability 的原子性。
+// 2. delta 解析复用 dist 导出的 `parseDeltaSpec`（与 Validator 同一解析器，单一真相源）。
+// 3. 操作顺序 RENAMED → MODIFIED → ADDED → REMOVED（改名先行，避免后续按名匹配失效）。
+// 4. **幂等**：同名同内容 → 跳过（重复 sync 安全）；**fail-closed**：目标缺失/命名冲突/
+//    已合并后主基被改动 → 抛错（调用方不写盘，整体退出非 0）。
+// 5. 主基格式不做规范化：按 `### Requirement:` 为块边界解析，兼容既有主基的
+//    `## ADDED Requirements` 容器形态（不改写既有段落结构）。
+
+const REQ_RE = /^###\s*Requirement:\s*(.+?)\s*$/;
+const H2_RE = /^##\s+/;
+
+/** dist 解析器惰性加载（与 cmd-sync 导入 Validator 同源）。 */
+let _parseDeltaSpec = null;
+async function loadParseDeltaSpec() {
+  if (!_parseDeltaSpec) {
+    const mod = await import('../../dist/index.js');
+    _parseDeltaSpec = mod.parseDeltaSpec;
+  }
+  return _parseDeltaSpec;
+}
+
+/** 归一化文本用于幂等比对：去行尾空白、去空行。 */
+function normalize(text) {
+  return text.split('\n').map(l => l.trimEnd()).filter(l => l.trim() !== '').join('\n').trim();
+}
+
+/** 取 requirement 块正文（去掉标题行与首尾空行）。 */
+function blockBody(blockLines) {
+  return blockLines.slice(1).join('\n').replace(/^\n+/, '').replace(/\s+$/, '');
+}
+
+/** 切掉 `#### Previous version` 子节（及其后内容）——用于幂等比对与旧内容提取。 */
+function stripPreviousVersion(body) {
+  const idx = body.search(/^####\s+Previous version\b/m);
+  return idx === -1 ? body : body.slice(0, idx).replace(/\s+$/, '');
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * 主基是否已带「本 change 合并过」的 Previous version 注记（重跑判定）。
+ * 词边界（`[\w-]` 两侧）避免 change 名互为前缀时误判（如 `v1-C3` 不应命中
+ * `v1-C3-session-governance` 的注记）。
+ */
+function hasMergedNote(body, changeName) {
+  const re = new RegExp(`^####\\s+Previous version\\b.*(?<![\\w-])${escapeRe(changeName)}(?![\\w-])`, 'm');
+  return re.test(body);
+}
+
+function renameNote(from, changeName) {
+  return `_Renamed from ${from} in ${changeName}._`;
+}
+
+function isRemovedSection(section) {
+  return typeof section === 'string' && /^Removed\b/i.test(section.trim());
+}
+
+/**
+ * 解析主基：以 `### Requirement:` 为块边界（块止于下一个 requirement / 下一个二级标题 / 文件末尾）。
+ * 记录每个块所属的二级段落名（section），用于区分正常区与 `## Removed` 段。
+ */
+function parseMain(content) {
+  const lines = content.split('\n');
+  const blocks = [];
+  let section = null;
+  let i = 0;
+  while (i < lines.length) {
+    const h2 = lines[i].match(/^##\s+(.+?)\s*$/);
+    if (h2) {
+      section = h2[1];
+      i++;
+      continue;
+    }
+    const m = lines[i].match(REQ_RE);
+    if (!m) {
+      i++;
+      continue;
+    }
+    let end = lines.length;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (REQ_RE.test(lines[j]) || H2_RE.test(lines[j])) {
+        end = j;
+        break;
+      }
+    }
+    blocks.push({ name: m[1].trim(), start: i, end, section });
+    i = end;
+  }
+  return { lines, blocks };
+}
+
+/** 在正常区（非 `## Removed` 段）按名查找 requirement 块。 */
+function findBlock(parsed, name) {
+  return parsed.blocks.find(b => b.name === name && !isRemovedSection(b.section)) || null;
+}
+
+/**
+ * ADDED 插入点：**正常区**（非 `## Removed` 段）最后一个 requirement 块之后
+ * （即下一个二级标题之前，或文件末尾）。
+ *
+ * 注意不能直接用最后一个块——若主基以 `## Removed` 段收尾，其内的条目也是块，
+ * 会把新 requirement 追加进已移除区。正常区无块时退化为「Removed 段之前 / 文件末尾」。
+ */
+function findAppendIndex(parsed) {
+  const normal = parsed.blocks.filter(b => !isRemovedSection(b.section));
+  if (normal.length === 0) {
+    const range = findRemovedSectionRange(parsed);
+    return range.start === -1 ? parsed.lines.length : range.start;
+  }
+  return normal[normal.length - 1].end;
+}
+
+/** 定位 `## Removed` 段的 [start, end)（end = 下一个二级标题或文件末尾）；无则 -1。 */
+function findRemovedSectionRange(parsed) {
+  const start = parsed.lines.findIndex(l => /^##\s+Removed\s*$/i.test(l));
+  if (start === -1) return { start: -1, end: -1 };
+  let end = parsed.lines.length;
+  for (let j = start + 1; j < parsed.lines.length; j++) {
+    if (H2_RE.test(parsed.lines[j])) {
+      end = j;
+      break;
+    }
+  }
+  return { start, end };
+}
+
+/** 段内尾部插入（自动补前导空行，条目自带尾随空行）。 */
+function appendAtSectionEnd(lines, idx, block) {
+  const pre = idx > 0 && lines[idx - 1].trim() !== '' ? [''] : [];
+  lines.splice(idx, 0, ...pre, ...block, '');
+}
+
+// ── 各操作的 apply（每次操作前重新解析，规避行号失效）────────────────────────
+
+function applyRenamed(content, plan, changeName, report) {
+  for (const { from, to } of plan.renamed) {
+    const parsed = parseMain(content);
+    const fromBlock = findBlock(parsed, from);
+    const toBlock = findBlock(parsed, to);
+
+    if (!fromBlock) {
+      // 幂等：源名已不存在，且目标名带本 change 的 rename 注记
+      const toText = toBlock ? parsed.lines.slice(toBlock.start, toBlock.end).join('\n') : '';
+      if (toBlock && toText.includes(renameNote(from, changeName))) {
+        report.skipped++;
+        continue;
+      }
+      throw new Error(`RENAMED 的源 requirement 不存在于主基：「${from}」（目标「${to}」）`);
+    }
+    if (toBlock) {
+      throw new Error(`RENAMED 的新名与主基既有 requirement 冲突：「${to}」（源「${from}」）`);
+    }
+    const lines = parsed.lines;
+    lines[fromBlock.start] = `### Requirement: ${to}`;
+    lines.splice(fromBlock.start + 1, 0, '', renameNote(from, changeName));
+    content = lines.join('\n');
+    report.renamed++;
+  }
+  return content;
+}
+
+function applyModified(content, plan, changeName, today, report) {
+  for (const block of plan.modified) {
+    const parsed = parseMain(content);
+    const target = findBlock(parsed, block.name);
+    if (!target) {
+      throw new Error(`MODIFIED 的目标 requirement 不存在于主基：「${block.name}」`);
+    }
+    const oldBody = blockBody(parsed.lines.slice(target.start, target.end));
+    const oldCore = stripPreviousVersion(oldBody);
+    const newBody = blockBody(block.raw.split('\n'));
+
+    if (normalize(oldCore) === normalize(newBody)) {
+      report.skipped++; // 幂等：内容一致（重复 sync 的安全路径）
+      continue;
+    }
+    if (hasMergedNote(oldBody, changeName)) {
+      throw new Error(
+        `MODIFIED 的目标「${block.name}」已合并且被后续改动（主基内容与 delta 不一致）——`
+        + `拒绝覆盖，请人工确认后用 git diff 核对主基与 delta`,
+      );
+    }
+
+    const replacement = [
+      block.raw.trimEnd(),
+      '',
+      `#### Previous version（${changeName} 更新于 ${today}）`,
+      '',
+      oldCore.trimEnd(),
+    ].join('\n').split('\n');
+
+    const lines = parsed.lines;
+    lines.splice(target.start, target.end - target.start, ...replacement);
+    content = lines.join('\n');
+    report.modified++;
+  }
+  return content;
+}
+
+function applyAdded(content, plan, report) {
+  for (const block of plan.added) {
+    const parsed = parseMain(content);
+    const existing = findBlock(parsed, block.name);
+    if (existing) {
+      const existingCore = stripPreviousVersion(blockBody(parsed.lines.slice(existing.start, existing.end)));
+      const newCore = blockBody(block.raw.split('\n'));
+      if (normalize(existingCore) === normalize(newCore)) {
+        report.skipped++; // 幂等：同名同内容
+        continue;
+      }
+      throw new Error(`ADDED 的名称与主基既有 requirement 冲突：「${block.name}」（内容不同）`);
+    }
+    const lines = parsed.lines;
+    appendAtSectionEnd(lines, findAppendIndex(parsed), block.raw.trimEnd().split('\n'));
+    content = lines.join('\n');
+    report.added++;
+  }
+  return content;
+}
+
+function applyRemoved(content, plan, changeName, today, report) {
+  for (const name of plan.removed) {
+    const parsed = parseMain(content);
+    const target = findBlock(parsed, name);
+
+    if (!target) {
+      // 幂等：该名已出现在 `## Removed` 段
+      const inRemoved = parsed.blocks.some(b => b.name === name && isRemovedSection(b.section));
+      if (inRemoved) {
+        report.skipped++;
+        continue;
+      }
+      throw new Error(`REMOVED 的目标 requirement 不存在于主基：「${name}」`);
+    }
+
+    const removedBody = blockBody(parsed.lines.slice(target.start, target.end));
+    const lines = parsed.lines;
+    lines.splice(target.start, target.end - target.start);
+    let text = lines.join('\n');
+
+    const entry = [
+      `### Requirement: ${name}`,
+      '',
+      `_Removed in ${changeName} on ${today}._`,
+      '',
+      removedBody.trimEnd(),
+    ];
+
+    const reparsed = parseMain(text);
+    const range = findRemovedSectionRange(reparsed);
+    if (range.start === -1) {
+      text = `${text.replace(/\s+$/, '')}\n\n## Removed\n\n${entry.join('\n')}\n`;
+    } else {
+      appendAtSectionEnd(reparsed.lines, range.end, entry);
+      text = reparsed.lines.join('\n');
+    }
+    content = text;
+    report.removed++;
+  }
+  return content;
+}
+
+// ── 公开入口 ────────────────────────────────────────────────────────────────
+
+function hasOperations(plan) {
+  return plan.added.length > 0 || plan.modified.length > 0
+    || plan.removed.length > 0 || plan.renamed.length > 0;
+}
+
+/**
+ * 将 delta spec 语义合并进主基。
+ *
+ * @param {string} mainContent 主基 spec 全文
+ * @param {string} deltaContent change 的 delta spec 全文（含 `## ADDED/MODIFIED/REMOVED/RENAMED Requirements`）
+ * @param {string} changeName change 名（写入 Previous version / Removed 注记）
+ * @param {{today?: string}} [options] `today` 可注入（测试确定性），默认取本地日期 YYYY-MM-DD
+ * @returns {Promise<{content: string, report: {renamed:number, modified:number, added:number, removed:number, skipped:number, noOps:boolean}}>}
+ * @throws {Error} 语义校验失败（fail-closed，调用方不得写盘）
+ */
+export async function mergeMainSpec(mainContent, deltaContent, changeName, options = {}) {
+  const parseDeltaSpec = await loadParseDeltaSpec();
+  const plan = parseDeltaSpec(deltaContent);
+  const today = options.today || new Date().toISOString().slice(0, 10);
+
+  if (!hasOperations(plan)) {
+    return {
+      content: mainContent,
+      report: { renamed: 0, modified: 0, added: 0, removed: 0, skipped: 0, noOps: true },
+    };
+  }
+
+  const report = { renamed: 0, modified: 0, added: 0, removed: 0, skipped: 0, noOps: false };
+  let content = mainContent;
+  content = applyRenamed(content, plan, changeName, report);
+  content = applyModified(content, plan, changeName, today, report);
+  content = applyAdded(content, plan, report);
+  content = applyRemoved(content, plan, changeName, today, report);
+  return { content, report };
+}
+
+/** delta 是否含任何可合并的操作段落（供 cmd-sync 判定 clean skip）。 */
+export async function deltaHasOperations(deltaContent) {
+  const parseDeltaSpec = await loadParseDeltaSpec();
+  return hasOperations(parseDeltaSpec(deltaContent));
+}

package/scripts/lib/state-loader.mjs

@@ -77,6 +77,12 @@ const BUILTIN_DEFAULTS = {
   // Tasks gate (v0.22 §85：hotfix/tweak 跳过 spec-writer 时显式跳过 tasks.md)
   tasks_skipped: null,
   tasks_skip_reason: null,
+  // Arch merge gate (v0.53.0 §110.2 加固 iii：arch-merged guard 维度的显式跳过键)
+  // 与 tasks_skipped / test_matrix_skipped 同一模式。用于 arch-merge 确为 no-op 的场景
+  // （如 change 的 architecture.md 无演进日志段且无聚合增量 → 全局台账不会出现
+  // `change:<name>`，若不给跳过键则 guard 永久 FAIL 无出路）。
+  arch_merge_skipped: null,
+  arch_merge_skip_reason: null,
   // 注意：schema_version 故意不在 BUILTIN_DEFAULTS 中（v0.13 §48.1）——
   // 它只由 `tf state init` 在 change 创建时打戳，字段缺失本身就是"存量 change"信号。
 };
@@ -203,6 +209,10 @@ export function writeState(changeDir, state) {
   lines.push('# === Tasks gate (v0.22 §85) ===');
   lines.push(`tasks_skipped: ${state.tasks_skipped ?? 'null'}`);
   lines.push(`tasks_skip_reason: ${state.tasks_skip_reason ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Arch merge gate (v0.53.0 §110.2) ===');
+  lines.push(`arch_merge_skipped: ${state.arch_merge_skipped ?? 'null'}`);
+  lines.push(`arch_merge_skip_reason: ${state.arch_merge_skip_reason ?? 'null'}`);
 
   fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
 }

package/scripts/lib/test-merge.mjs

@@ -13,7 +13,7 @@
  * 5. rewriteIndex — 统计模块数/case 数/deferred 数，重写 INDEX.md
  * 6. gitCommit — 单次原子提交
  *
- * 回写顺序：arch-merge → prototype-sync → test-merge → compound promotion
+ * 回写顺序：arch-merge → state transition closing → prototype-sync → test-merge → compound promotion
  *
  * v0.38.0（feedback 2026-08-05 修复 + E2E 层级）：
  * - resolveDeferred 只删 Deferred Items 段内被覆盖行（原全文件 regex 误删 Current Cases）

package/scripts/lib/test-record.mjs

@@ -16,9 +16,20 @@ export const SUPPORTED_RUNNERS = ['maven-surefire', 'jest', 'pytest'];
 
 // ── 解析器（全部返回 { total, passed, failed, skipped } 或 null）────────────
 
-/** maven surefire 控制台汇总行（多模块累加）："Tests run: 42, Failures: 0, Errors: 0, Skipped: 2" */
+/**
+ * maven surefire 控制台解析：只累加**模块汇总结行**（多模块累加），排除类级明细行。
+ *
+ * v0.24 §97.3.1：两类行的判据是 `Skipped: N` 之后的内容——
+ * - 类级行：`Tests run: 7, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.5 s -- in com.FooTest`
+ *   （surefire 2.x 为 `sec - in`、3.x 为 `s -- in`，`Time elapsed:` 前缀为共同判据）；
+ * - 汇总行：`Tests run: 134, Failures: 0, Errors: 0, Skipped: 0`（其后即行尾，或仅余 ANSI 尾码）。
+ *
+ * 旧实现无差别累加全部匹配行：带 ANSI 时类级行的计数数字被颜色码包裹
+ * （`Tests run: \x1b[0;1;32m7\x1b[m, …`）而"侥幸"不匹配，剥离 ANSI 后类级行 + 汇总行
+ * 同时命中 → 双计（实测 134 → 268）。负向前瞻令 ANSI 剥离前后行为一致。
+ */
 export function parseMavenSurefire(text) {
-  const re = /Tests run:\s*(\d+),\s*Failures:\s*(\d+),\s*Errors:\s*(\d+),\s*Skipped:\s*(\d+)/g;
+  const re = /Tests run:\s*(\d+),\s*Failures:\s*(\d+),\s*Errors:\s*(\d+),\s*Skipped:\s*(\d+)(?!,\s*Time elapsed)/g;
   let m;
   let total = 0; let failures = 0; let errors = 0; let skipped = 0;
   let found = false;
@@ -121,8 +132,24 @@ export function parsePytest(text) {
   return { total, passed, failed, skipped };
 }
 
+/**
+ * maven-surefire 文件输入入口（v0.24 §97.3.2）：junit XML 优先，与 pytest 对称。
+ *
+ * 目录输入走 parseSurefireReportDir；文件输入经此入口——内容含 `<testsuites>` 时
+ * 结构化解析（权威口径，免疫 ANSI / 类级行 / 日志截断），否则按控制台文本解析。
+ * 修复前：detectRunner 嗅探 XML 后归入 maven-surefire，但该 runner 的解析器只认控制台
+ * 文本 → 单个 surefire XML 文件解析失败（目录可用是因其走了专用分支）。
+ */
+function parseMavenSurefireInput(text) {
+  if (looksLikeJunitXml(text)) {
+    const xml = parseJunitXml(text);
+    if (xml) return xml;
+  }
+  return parseMavenSurefire(text);
+}
+
 const PARSERS = {
-  'maven-surefire': parseMavenSurefire,
+  'maven-surefire': parseMavenSurefireInput,
   jest: parseJest,
   pytest: parsePytest,
 };
@@ -265,9 +292,12 @@ export async function run(args) {
   }
   if (!stats) {
     // v0.49.0 §83.3.6：错误信息附输入形态指引（原提示对"传了 XML"的用户无帮助）
+    // v0.24 §97.3.3：maven-surefire 补 XML 形态与"仅类级明细行"说明（类级行已不再计入）
     const hint = runner === 'pytest'
       ? 'pytest accepts a terminal summary or a junit XML report (pytest --junitxml=<path>).'
-      : `Supported runners: ${SUPPORTED_RUNNERS.join(', ')} (or pass --runner explicitly).`;
+      : runner === 'maven-surefire'
+        ? 'maven-surefire accepts a console summary (module summary lines, not per-class detail lines), a single surefire XML report, or a target/surefire-reports directory.'
+        : `Supported runners: ${SUPPORTED_RUNNERS.join(', ')} (or pass --runner explicitly).`;
     console.error(`Could not parse ${runner} output in ${fromPath} — no recognizable test summary found.\n${hint}`);
     process.exit(1);
   }

package/scripts/team-flow.mjs

@@ -67,6 +67,7 @@ Commands:
   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
+  arch scaffold         Scaffold global docs/architecture/ ledger in generator format (v0.53.0 §102)
   arch precheck <change-dir> [--json]
                         Emit deterministic architecture-gate evidence (v0.22 §88; evidence only, exit 0)
   arch-merge <change-dir> [--project-root <path>] [--dry-run]
@@ -198,7 +199,19 @@ async function main() {
   }
 
   const mod = await COMMANDS[command]();
-  await mod.run(commandArgs);
+  const result = await mod.run(commandArgs);
+  // v0.53.0 §104.2.3：命令以结构化失败结果结束 → 传播非零退出码。
+  //
+  // 背景：`arch-merge` 的 `[FAIL]` 汇总与 `arch-merge FAILED: N failure(s).` 消息
+  // 原本只在 `import.meta.url === process.argv[1]` 的**直调块**里设 `process.exitCode`，
+  // 而经 `tf` 调用走的是本 dispatcher（不消费返回值）→ **`tf arch-merge` 实测恒 exit 0**，
+  // 与 SKILL.md 承诺的"可能以非零退出码结束"不符，`tf arch-merge <dir> && tf state
+  // transition closing` 这类链式写法拿不到失败信号。
+  //
+  // 放在 dispatcher 而非 `run()` 内：`run()` 被 import 时不应设全局 exitCode
+  // （既有测试守护 "does not set process.exitCode when imported"）。
+  // 守卫 `Array.isArray(result.failures)`：仅对返回该结构的命令生效，其余命令不受影响。
+  if (result && Array.isArray(result.failures) && result.failures.length > 0) process.exitCode = 1;
 }
 
 main().catch(err => {

package/skills/architecture-design/templates/api.md

@@ -30,23 +30,29 @@ api_contract_manager: swagger
 
 ## 2. To-Be 增量设计
 
+> ⚠ **占位符必须替换**：示例行的路径写作 `<endpoint>` 形式而非 `/api/xxx` 这类**看起来像真实路径**的字符串。
+> 原因（v0.53.0 §115.6）：`/api/xxx` 是**合法的路径形状**，arch-merge 的端点提取器会**正常提取**它，
+> 且新加的"候选>0 且提取=0 → 失败"与"覆盖率<0.5 → 告警"两条对账判据**都不会触发**
+> （占位行被当作真实端点）。后果是占位符被计入全局 `API-INDEX.md` 与 `INDEX.md` 的「端点数量」
+> ——与 v0.25 §101.3 记录的症状同源。`<endpoint>` 不以 `/` 开头，提取器天然拒绝。
+
 ### 2.1 Command API（改状态）
 
 | 端点 | 方法 | 聚合 | 事务边界 | 说明 |
 |------|------|------|---------|------|
-| /api/xxx | POST | XxxAggregate | t_xxx 事务 | 简要说明 |
+| `<endpoint>` | POST | XxxAggregate | t_xxx 事务 | 简要说明 |
 
 ### 2.2 Read API（有逻辑不改状态）
 
 | 端点 | 方法 | 聚合 | 数据来源 | 说明 |
 |------|------|------|---------|------|
-| /api/xxx/{id}/detail | GET | XxxAggregate | t_xxx + JOIN | 简要说明 |
+| `<endpoint>/{id}` | GET | XxxAggregate | t_xxx + JOIN | 简要说明 |
 
 ### 2.3 Query API（纯查询）
 
 | 端点 | 方法 | 查询模型 | 阻断测试 | 说明 |
 |------|------|---------|---------|------|
-| /api/dashboard/xxx-stats | GET | XxxStatsView | 阻断=继续 → 数据服务 | 简要说明 |
+| `<endpoint>` | GET | XxxStatsView | 阻断=继续 → 数据服务 | 简要说明 |
 
 > **阻断测试说明**：将服务阻断 1h，下游不能继续 → 业务服务；能继续 → 数据服务
 
@@ -56,7 +62,7 @@ api_contract_manager: swagger
 
 | API 端点 | 对应数据实体 | 对齐状态 | 不一致说明 |
 |---------|------------|---------|-----------|
-| /api/xxx | t_xxx | ✅ 对齐 | — |
+| `<endpoint>` | t_xxx | ✅ 对齐 | — |
 
 ### 3.1 术语命名统一性