@xulthekl/team-flow 0.51.0 → 0.52.0

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.51.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.52.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback + independent business analysis. 26 skills + 17 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.51.0",
+      "version": "0.52.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.51.0"
+    "version": "0.52.0"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.51.0"
+    "version": "0.52.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, independent business analysis, and local HTML prototyping.",
-      "version": "0.51.0",
+      "version": "0.52.0",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -4,6 +4,47 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.52.0] - 2026-09-10
+
+### Fixed（CLI 命令语义分裂修复：spec 合并 / 测试解析 / 路径清洗）
+
+设计增强方案 v0.24（§96-§98）。来源：emp-auth v1-C3 收口 3 条 workflow-feedback（20260910-093040 / 093041 / 093042）+ 并入 20260910-002000。
+
+**R1 `tf sync`：文件覆盖 → 语义合并（P1）**
+
+- **根因**：`cmd-sync.mjs` 为纯文件拷贝（readFileSync → writeFileSync），与 `spec-merger` SKILL.md 定义的 ADDED/MODIFIED/REMOVED/RENAMED 语义合并**长期分裂**——主基已存在的 capability 被 delta 整体覆盖，静默删除前序 change 交付的 Requirement（实测 C3 覆盖 C2，`git diff --numstat` = 168/60）
+- **修复**：新增 `scripts/lib/spec-merge.mjs`（纯函数式合并器，复用 dist 的 `parseDeltaSpec`）；`tf sync` 改为三分支——主基不存在→拷贝 / 主基存在→语义合并 / 无操作段落→clean skip；全部 capability 内存计算后**原子写盘**（fail-closed：任一失败不写任何文件、退出非 0）；全部成功后写 `spec_merged: true`（并入 20260910-002000：此前唯一写入路径是人工 `tf state set`，`specs-merged` guard 恒 FAIL）
+- **幂等与边界**：同名同内容 → skipped（重复执行安全）；MODIFIED 目标缺失 / ADDED 名称冲突 / 已合并后被后续改动 → 报错拒绝覆盖
+- **同步**：`skills/spec-merger/SKILL.md` 改写（命令承担合并，skill 转为「执行 → 核对报告 → 异常处理」）；`docs/usage-guide.md` 描述更新
+- **P3 自审补修**：① ADDED 插入点落入 `## Removed` 段（主基以 Removed 收尾时其内条目也被当作块）② change 名互为前缀时「已合并」注记误判
+- **P4 评审加固**：① `abandoned` change 命令层拒绝（原仅 SKILL.md 技能层 Guard，无法机械保证）② delta 无操作段落由普通信息升级为**告警**（畸形 delta 如 `## ADDED Requirement` 少 s 会解析为「无操作」而非错误，静默跳过等同掩盖缺口）
+
+**R2 `tf test record`：surefire 解析修正 + XML 对称性（P2）**
+
+- **根因 A**：`parseMavenSurefire` 全局正则累加**全部** `Tests run:` 匹配行——带 ANSI 时类级行的计数数字被颜色码包裹而"侥幸"不匹配，一旦剥离 ANSI 类级行 + 汇总行双计（实测 134 → 268，恰为 2×）
+- **根因 B**：`detectRunner` 嗅探 junit XML 归入 maven-surefire，但该 runner 的解析器只认控制台文本 → 单个 surefire XML 文件解析失败（pytest 有 XML 优先逻辑，支持不对称）
+- **修复**：类级行以 `, Time elapsed` 负向前瞻排除（surefire 2.x `sec - in` / 3.x `s -- in` 统一，ANSI 剥离前后行为一致）；maven-surefire 补 XML 优先入口（与 pytest 对称，单 XML 文件可用）；解析失败提示补输入形态说明
+
+**R3 `tf publish`：porcelain 首行保真（P3）**
+
+- **根因**：`git()` 封装的 `.trim()` 吃掉 `git status --porcelain` 首行前导空格（` M path` → `M path`），`parsePorcelainPaths` 的 `slice(3)` 按固定宽度切片切掉路径首字符（`changes/…` → `hanges/…`）→ 白名单失配 → 误报「白名单之外存在未提交文件」（而 `git add` 使用未损坏白名单，文件实际被提交）。**路径截断与告警失配是同一根因**（非两个独立缺陷）
+- **修复**：只裁首尾换行（`replace(/^[\r\n]+|[\r\n]+$/g, '')`）；`parsePorcelainPaths` 增加输入形态断言（fail-loud 第二道防线，污染输入不再静默产出错误路径）；`cmd-publish` / `arch-merge` 的 catch 打印告警（防断言被静默吞掉）；告警文案中性化（「不提交」→「本次不提交，提交范围以白名单为准」，与 v0.51.0 arch-merge 对齐）
+- **横展**：全部 porcelain 消费方 4 处已核（仅 `cmd-publish` 经清洗封装，其余安全）
+
+### Tests
+
+新增 36 用例：spec-merge 17（含幂等 / fail-closed / Removed 落位 / 前缀名）+ cmd-sync-merge 7（C2→C3 复刻 / 原子性 / fail-closed / abandoned / 无操作段落告警）+ cmd-publish 2（首行保真回归）+ git-utils 2（污染断言）+ test-record 8（类级行 / ANSI / 真实日志复刻 / 单 XML）。**845/845 通过**（另 deterministic E2E 68/68）。
+
+## [0.51.1] - 2026-09-09
+
+### Fixed（SessionStart 上下文注入静默失效：JSON 转义缺位）
+
+- **根因**：`hooks/session-start` 的 `msg` 中 `"Base directory for this skill"` 的双引号在 bash 双引号串内被解析为裸 `"`，又被 `printf` 直接拼进 JSON 字符串 → SessionStart 输出非法 JSON，Claude Code 解析失败，三条 `EXTREMELY_IMPORTANT` 上下文规则（工作流触发约束 / 工作区目录规则 / 语言要求）**从未注入**
+- **影响范围**：v0.26.0（`aafdc54`，2026-07-29）引入，至 v0.51.0 已 6 周
+- **修复**：printf 前新增 `msg_esc="$(printf '%s' "$msg" | sed 's/"/\\"/g')"`，三处 printf 改用转义后变量。与 `hooks/pre-tool-use-guard:168` 既有范式一致——只转引号不转反斜杠（`\n` 是有意保留的 JSON 换行转义，全量转义会退化为字面两字符）
+- **测试守护**（根因的根因）：新增 `tests/lib/hook-session-start.test.mjs`，断言三平台分支（Claude Code / Cursor / 默认）输出均为合法 JSON、三条规则完整、换行解析为真实换行。同目录 `pre-tool-use-guard` 早有 9 case 判定矩阵测试，本 hook 此前仅有版本号同步测试——缺的不是方法，是断言
+- **横展**：全插件手工拼 JSON 输出点仅此一处；`.cursor/` 无副本，`.zcode/` 无 hook 副本
+
 ## [0.51.0] - 2026-09-09
 
 ### Fixed（CLI 静默失效治理：仓清单 / 白名单 / 严重度序）

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.51.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.52.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.51.0**。
+当前发布版本：**v0.52.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.51.0`
+> 当前版本：`v0.52.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.51.0`
+- Current: `v0.52.0`
 - v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)

package/docs/usage-guide.md

@@ -407,7 +407,7 @@ tf execution refresh-hash <dir>        # 不 bump revision 刷新 plan 内 hash
 tf test record <dir> --from <output> [--runner auto|maven-surefire|jest|pytest]
 tf test-merge <dir> [--dry-run]        # 测试矩阵 → docs/test-ledger/
 tf test-matrix-export <in.json> <out.md>   # glaf4 矩阵格式桥接
-tf sync <dir>                          # delta specs 合并进主 spec 基
+tf sync <dir>                          # delta specs 语义合并进主 spec 基（ADDED/MODIFIED/REMOVED/RENAMED；幂等 + fail-closed，自动写 spec_merged）
 tf arch-merge <dir> [--dry-run]        # 架构增量 → docs/architecture/
 tf prototype-sync <dir>                # UX 增量 → 全局 prototype/
 tf publish --prd|--arch|--changes <dir>|--all [--push] [--dry-run]

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev) + compound-engineering core subset + architecture-design (4A/DDD) + prototype (local HTML) + business-analysis (independent requirement/scenario artifact). 26 skills, one install.",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.51.0: auto-sync CLI version with plugin version
+# v0.52.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.51.0"
+PLUGIN_VERSION="0.52.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version
@@ -47,13 +47,21 @@ sync_tf_version
 
 msg="<EXTREMELY_IMPORTANT>\nYou have team-flow installed. Invoke /team-flow:workflow-start or /team-flow:workflow-orchestrator ONLY when active team-flow artifacts exist (\`.team-flow.yaml\`, \`proposal.md\`, \`execution-contract.md\`, \`specs/\`) or the user explicitly requests it. For ordinary coding tasks, do NOT invoke them.\n</EXTREMELY_IMPORTANT>\n<EXTREMELY_IMPORTANT>\n## Workspace Directory Rule\n\"Base directory for this skill\" = skill source location (read SKILL.md/references/ ONLY). User project = \`pwd\`. ALL project artifacts (changes/, requirement/, docs/, .team-flow/, etc.) MUST operate under \`pwd\`, NEVER the skill base directory. Run \`pwd\` first in every skill execution.\n</EXTREMELY_IMPORTANT>\n<EXTREMELY_IMPORTANT>\n## Language\nCommunicate with the user in Chinese (中文). Technical terms, code, and commands remain in English.\n</EXTREMELY_IMPORTANT>"
 
+# JSON-escape the message before embedding it into the printf templates below.
+# Technique from hooks/pre-tool-use-guard (reason_esc), intentionally narrower:
+# that hook escapes backslashes too, but here the literal `\n` sequences above
+# are intentional JSON newline escapes — escaping backslashes as well would
+# degrade them to literal two-character sequences. Do NOT "align" the two hooks.
+# Regression guard: tests/lib/hook-session-start.test.mjs
+msg_esc="$(printf '%s' "$msg" | sed 's/"/\\"/g')"
+
 # Three platforms share the same message, only output format differs.
 if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
-  printf '{\n  "additional_context": "%s"\n}\n' "$msg"
+  printf '{\n  "additional_context": "%s"\n}\n' "$msg_esc"
 elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
-  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$msg"
+  printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$msg_esc"
 else
-  printf '{\n  "additionalContext": "%s"\n}\n' "$msg"
+  printf '{\n  "additionalContext": "%s"\n}\n' "$msg_esc"
 fi
 
 exit 0

package/llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.51.0.
+Current version: v0.52.0.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xulthekl/team-flow",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Unified plugin (26 skills + 17 agents) integrating team-flow, compound-engineering, architecture-design, prototype, design-system, workflow-orchestrator, workflow-bootstrap, e2e, session-handoff, workflow-feedback, business-analysis for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking) + business-analysis (independent requirement/scenario artifact). 26 skills + 17 agents, one install.",
   "author": {
     "name": "LT"

package/scripts/lib/arch-merge.mjs

@@ -459,7 +459,10 @@ function detectUntouchedDirtyFiles(projectRoot, globalArchDir, touchedFiles) {
     // 路径口径统一为「相对 projectRoot 的绝对路径」后再与白名单比对，不依赖 process.cwd()。
     const touched = new Set(touchedFiles.map(p => resolve(projectRoot, p)));
     return parsePorcelainPaths(status).filter(p => p && !touched.has(resolve(projectRoot, p)));
-  } catch {
+  } catch (e) {
+    // v0.24 §98.3.2：解析失败不得静默（旧实现静默返回 [] = 漏报）。commit 侧仍有
+    // `git commit -- <白名单>` 与提交后回读比对两道防线，故此处仅告警不阻断。
+    console.warn(`  [WARN] 脏文件检测失败（${e.message}）——跳过该告警，提交范围仍以白名单为准。`);
     return [];
   }
 }

package/scripts/lib/cmd-publish.mjs

@@ -54,9 +54,19 @@ function parseArgv(argv) {
   return parsed;
 }
 
-/** git 执行封装（统一 encoding + 错误降级）。 */
+/**
+ * git 执行封装（统一 encoding）。
+ *
+ * v0.24 §98.3.1：**只裁首尾换行，不用 `.trim()`**。`status --porcelain` 是固定宽度
+ * 格式，首行可能是 ` M path`（X 位空格 = 未暂存修改）——`.trim()` 会吃掉行首空格，
+ * 令 parsePorcelainPaths 的 `slice(3)` 切掉路径首字符（`changes/…` → `hanges/…`），
+ * 路径损坏 → 白名单失配 → 误报「白名单之外存在未提交文件」（而 git add 用的白名单
+ * 未损坏，文件实际被提交，形成"告警与行为不一致"）。
+ * 对 `branch --show-current` / `rev-parse` 等单行输出，只裁尾换行与 trim 等效。
+ */
 function git(cwd, ...args) {
-  return execFileSync('git', args, { encoding: 'utf-8', cwd, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  return execFileSync('git', args, { encoding: 'utf-8', cwd, stdio: ['ignore', 'pipe', 'pipe'] })
+    .replace(/^[\r\n]+|[\r\n]+$/g, '');
 }
 
 function isDir(p) {
@@ -147,7 +157,10 @@ function detectOutsideDirty(projectRoot, whitelist) {
         }
         return true;
       });
-  } catch {
+  } catch (e) {
+    // v0.24 §98.3.2：解析失败不得静默（旧实现静默返回 [] = 漏报）。提交主流程不受影响，
+    // 但必须让使用者知道"本次白名单外检测未生效"，改以 git status 原始输出人工核对。
+    console.warn(`[WARN] 白名单外脏文件检测失败（${e.message}）——本次不输出该告警，提交范围仍以白名单为准。`);
     return [];
   }
 }
@@ -209,7 +222,9 @@ export async function run(args = []) {
   // 脏文件检测（target 之外）→ 告警不阻断
   const outsideDirty = detectOutsideDirty(projectRoot, whitelist);
   if (outsideDirty.length > 0) {
-    console.warn(`[WARN] 白名单之外存在 ${outsideDirty.length} 个未提交文件（不提交）：`);
+    // v0.24 §98：文案中性化（与 v0.51.0 arch-merge 同类处理对齐）——「不提交」易被误读为
+    // 永久不提交（这些文件可能由其他流程提交），准确表述为「本次不提交 + 范围以白名单为准」。
+    console.warn(`[WARN] 白名单之外存在 ${outsideDirty.length} 个未提交文件（本次不提交，提交范围以白名单为准）：`);
     for (const f of outsideDirty.slice(0, 5)) console.warn(`  - ${f}`);
     if (outsideDirty.length > 5) console.warn(`  ... 等 ${outsideDirty.length} 个`);
   }

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/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/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/skills/spec-merger/SKILL.md

@@ -1,66 +1,71 @@
 ---
 name: spec-merger
-description: Sync delta specs to main specs after closure. Invoke when a change is closing, delta specs need merging into the main spec base, or when detecting spec drift across multiple changes.
+description: Sync delta specs to main specs at change closing, before the executing→closing guard runs. Invoke when a change is closing, delta specs need merging into the main spec base, or when cross-change requirement conflicts need detection.
 ---
 
 # Spec Merger
 
 After a change completes, delta specs (ADDED/MODIFIED/REMOVED/RENAMED) must be merged into the main spec base. **Specs that aren't synced become lies.**
 
-## Pre-Flight Checks
+Since v0.52.0 (design v0.24 §96), `tf sync` performs the merge **deterministically** — the command
+is no longer a file copy: it applies ADDED/MODIFIED/REMOVED/RENAMED semantics, is idempotent on
+re-run, fails closed (nothing written if any capability fails), and records `spec_merged: true`
+itself. This skill's job is: guard → run the command → **verify its report** → handle exceptions.
 
-### Conflict Detection
-Run `tf sync <change-dir>`. If conflicts are detected (same requirement modified by multiple changes), present the conflict list to the user for resolution order.
+**Locations**: the main spec base is `specs/<capability>/spec.md` at the **workspace root**. The
+delta is the change-local `<change-dir>/specs/<capability>/spec.md` — do not confuse the two.
+Run the command and the `git diff` verification from the workspace root.
 
-### Abandoned Change Guard
-Check if the change is `abandoned`. If so → STOP: "Abandoned changes cannot be synced. Delta specs are preserved for reference but must not be merged."
+## Pre-Flight Guard
 
-## Sync Process
+Check if the change is `abandoned` (`.team-flow.yaml` → `state: abandoned`). If so → STOP:
+"Abandoned changes cannot be synced. Delta specs are preserved for reference but must not be merged."
+(`tf sync` also rejects abandoned changes at the command layer — this step is a fast-fail courtesy.)
 
-### Step 1: Identify Deltas
-Each `specs/<capability>/spec.md` under the change folder contains delta operations under `## ADDED/MODIFIED/REMOVED/RENAMED Requirements`.
+Only sync changes whose planning artifacts are frozen and whose implementation is complete — the command does not verify this for you.
 
-### Step 2: Apply by Operation
+## Run Sync
 
-**ADDED**: Append to `specs/<capability>/spec.md`. Create the main spec if it doesn't exist. Insert before any REMOVED section.
+Run `tf sync <change-dir>`. The command performs, in order:
 
-**MODIFIED**: Match on `### Requirement: <name>`. Replace description and scenarios. Preserve original in a `### Previous version` subsection. Flag if requirement doesn't exist in main spec.
+1. **Abandoned rejection** — exits non-zero, writes nothing.
+2. **Cross-change conflict detection** — same requirement MODIFIED/RENAMED by multiple unsynced changes → lists the conflicts and exits non-zero (resolve order manually; sync one change at a time).
+3. **Per-capability merge** (in memory) — main spec absent → copy as-is (capability first delivery, checked first); delta has no operation sections → clean skip (only when the main spec already exists); otherwise semantic merge.
+4. **Unified write** — only if every capability succeeded (fail-closed: any failure writes nothing).
+5. **State write** — `spec_merged: true` (the `executing → closing` guard reads this flag; no manual `tf state set` needed).
 
-**REMOVED**: Move to `## Removed` section with deprecation note: reason, migration, and change name. Flag if requirement doesn't exist.
+If conflicts are detected, present the conflict list to the user for resolution order.
 
-**RENAMED**: Match old name, change header to new name, add `_Renamed from <old> in <change>_`. Flag if new name collides with existing.
+## Merge Semantics (verification summary — not exhaustive)
 
-### Step 3: Conflict Detection
-Before executing, detect:
-- Same requirement modified by multiple unsynced changes → manual resolution
-- RENAMED target collides with existing requirement → manual resolution
-- MODIFIED/REMOVED targeting nonexistent requirements → flag
+| Operation | Behavior |
+|-----------|----------|
+| **ADDED** | Append to the main spec (before any `## Removed` section). Same name + identical content → skipped; same name + different content → error. |
+| **MODIFIED** | Replace the whole `### Requirement: <name>` block; the original is kept as `#### Previous version（<change> 更新于 <date>）` (**most recent generation only** — earlier history stays in git). Missing target → error. |
+| **REMOVED** | Move the block into `## Removed` with a `_Removed in <change> on <date>._` note (original body preserved). Missing target (and not already in `## Removed`) → error. |
+| **RENAMED** | Rename the header + `_Renamed from <old> in <change>._` note. Missing source or name collision → error. |
 
-### Step 4: Execute Merge
-Apply changes. Do NOT delete delta specs — they remain for traceability. After merge, validate: no duplicate requirement names, no orphaned references, REMOVED section clearly separated.
+**Verification (always do this, from the workspace root)**:
 
-### Step 5: Report
-Output sync report table: Capability, ADDED/MODIFIED/REMOVED/RENAMED counts, Status (✓/⚠). Summary with totals and unresolved conflicts.
+1. Read the per-capability report (`ADDED n / MODIFIED n / REMOVED n / RENAMED n / skipped n`).
+2. `git diff specs/` — confirm no pre-existing requirement was dropped; confirm `#### Previous version` is present for MODIFIED. (A second MODIFIED replaces the first generation's note — expected, not a loss.)
+3. Counts match the delta sections. `skipped > 0` means a re-run or already-merged content.
 
 ## Guardrails
 
 - Do not delete delta spec files (historical record)
+- Do not hand-edit main specs while a sync is pending — a later sync reports "已合并且被后续改动" (merged then modified) and refuses to overwrite
 - Do not auto-resolve conflicts across changes
-- Do not merge specs for unverified changes
-- Validate main spec consistency after each capability merge
 
 ## Post-Sync
 
-1. Report results. If no conflicts → ready to archive. If conflicts → user resolves before archive.
+1. Report results (command report + diff verification). If no conflicts → ready to archive.
 2. Change folder (including deltas) remains for traceability.
-3. Record that merging is complete so the `executing → closing` guard allows closure:
-   ```bash
-   tf state set <change-dir> spec_merged true
-   ```
-   (If the change had no delta sections, still set `spec_merged true` — there was nothing to merge.)
+3. `spec_merged` is written by the command — no manual step.
 
 ## Exception Handling
 
-- **Parse failures**: Report file and section. Do not attempt partial merges.
-- **No deltas**: If change has no delta sections, report nothing to merge and exit cleanly.
-- **User interruption**: On resume, check for merge conflict markers before proceeding.
+- **Merge aborted (fail-closed)**: the command prints "Sync aborted（未写入任何文件）" with the reason (e.g. MODIFIED target missing, ADDED name conflict). Nothing was written — fix the delta or the main spec, then re-run.
+- **Refused overwrite ("已合并且被后续改动")**: the requirement was modified after a previous merge. Inspect `git diff specs/<capability>/spec.md`: intended evolution → regenerate the delta's MODIFIED section against the current main spec; unintended → restore the main spec, then re-run.
+- **No deltas / malformed input**: a capability with no recognizable operation sections is reported as `No delta operations found` (warning) and skipped. If that capability *should* have changes, check the delta's section headers (`## ADDED/MODIFIED/REMOVED/RENAMED Requirements`) for typos — a mistyped header parses as "no operations", not as a parse error. `spec_merged` is still recorded so the guard passes.
+- **User interruption**: just re-run `tf sync` — it is idempotent and fail-closed (no partial state to clean up).