@xulthekl/team-flow 0.51.1 → 0.53.0

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

@@ -1,3 +1,3 @@
-# team-flow v0.51.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.53.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.1",
+      "version": "0.53.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.51.1",
+  "version": "0.53.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.1",
+  "version": "0.53.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.1"
+    "version": "0.53.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.1",
+  "version": "0.53.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.1"
+    "version": "0.53.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.1",
+      "version": "0.53.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -166,7 +166,7 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   复利回写层（closing 期）
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  arch-merge → prototype-sync（顺序提交）
+  arch-merge → state transition → prototype-sync（顺序提交）
   复利晋升：change 内经验 → 全局 docs/solutions/
   全局 ARCHITECTURE.md / DATABASE.md / prototype/ / design-system.md
   │
@@ -241,7 +241,7 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 | spec-writer | 规格编写 agent——产出并打磨 proposal.md / specs/ / design.md / tasks.md 四件规划制品（可写型，规划制品唯一所有者；need-explorer DP-1 后、contract-builder 前） | Read/Bash/Grep/Glob/Write/Edit | workflow-start 路由时作为子代理 dispatch |
 | contract-builder | 执行契约 agent——将规划制品压缩为单一执行握手 execution-contract.md、守 DP-3 批准门（可写型，契约文件唯一所有者；spec-writer DP-2 后、build-executor 前） | Read/Bash/Grep/Glob/Write/Edit | workflow-start 路由时作为子代理 dispatch |
 | build-executor | 构建执行 agent——以契约为权威驱动 TDD 批次实施（SDD/Inline/Batch Inline）、守 TDD Iron Law（可写型，实施代码所有者；契约 DP-3 批准后、release-archivist 前） | Read/Bash/Grep/Glob/Write/Edit | workflow-start 路由时作为子代理 dispatch |
-| release-archivist | 发布归档 agent——执行验证、产出 closing 总结、完成归档就绪（arch-merge → prototype-sync → 复利晋升）（可写型，归档制品所有者；build-executor 后、change 关闭前） | Read/Bash/Grep/Glob/Write/Edit | workflow-start 路由时作为子代理 dispatch |
+| release-archivist | 发布归档 agent——执行验证、产出 closing 总结、完成归档就绪（arch-merge → state transition → prototype-sync → 复利晋升；顺序定义见 Skill）（可写型，归档制品所有者；build-executor 后、change 关闭前） | Read/Bash/Grep/Glob/Write/Edit | workflow-start 路由时作为子代理 dispatch |
 | business-analysis | 独立业务分析 agent——将任意输入整理为 requirement/vN/business-analysis.md，多轮单问澄清、待办记录、新增/更新模式，写入前阻塞确认 | Read/Bash/Grep/Glob/Write/Edit | 独立触发，不进入 workflow-orchestrator 核心流程（v0.44.0） |
 
 ## 复利贯穿机制（v0.5 新增）
@@ -300,6 +300,6 @@ TypeScript interfaces + regex-based parsers. Compiles to `dist/` (ES2022 + NodeN
 ## 关键约束
 - **原型全局一份**、与 PRD 同级、git 分支隔离版本；change 不直接拥有原型文件（引用全局 `prototype/` 作 UI 契约）。
 - **design.md 不可变**：架构增量经 `arch-merge` 回写全局 `ARCHITECTURE.md`，不就地改 change 的 design.md。
-- **顺序提交**：`arch-merge` → `prototype-sync`（同一 change closing 内），避免全局文档半更新态。
+- **顺序提交**：`arch-merge` → `state transition closing` → `prototype-sync`（同一 change closing 内；v0.53.0 起状态转换插在 arch-merge 之后——`executing→closing` 挂 `arch-merged` 门禁，未回写则转换被拒），避免全局文档半更新态。
 - **膨胀防控**：`prototype/components/` 必须复用 `design-system.md`，禁止页面内联样式漂移；新增组件先沉淀进 design-system 再引用。
 - **分支约定**：原型随 PRD 当前版本分支维护；change 引用其所在 PRD 版本分支的 `prototype/`。

package/CHANGELOG.md

@@ -4,6 +4,106 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.53.0] - 2026-09-10
+
+### Added（架构台账回写门禁：`arch-merged` 维度 + B' 时序前移）
+
+设计增强方案 v0.25（§101-§115）。来源：emp-auth v1 收口 2 条 workflow-feedback（20260910-175800 / 175801）+ 1 条零聚合门禁（20260910-000823）。
+
+**核心承诺**：team-flow 的一大原则是「每次迭代后的架构变更（聚合 / API / DB）都必须合并进台账文档」。本版把这条原则从**文档承诺**变为**代码强制**。
+
+- **新增 guard 维度 `arch-merged`**（挂 `executing→closing`）：校验全局 `docs/architecture/ARCHITECTURE.md` 是否已含本 change 的增量。判据**双通道**——marker 区来源列 `change:<name>` **或** 演进日志锚 `### change:<name>`（单通道会与 R11 互锁，见 §110）。豁免面：`arch_design_decision` 为 `null`/`skipped`、`arch_merge_skipped=true`、`arch_baseline` 缺失（存量信号）。该转换由 **9 维增至 10 维**；guard 维度全量 **19**（`guard-dimensions.test.mjs` 对其中 13 维断言 pass/fail，其余 6 维由 `tests/lib/` 层覆盖——映射见该测试文件头部）。
+- **回写链时序前移（B' 方案 §110）**：`tf arch-merge` 从「状态转换之后」前移到「**之前**」。新顺序 **`arch-merge → state transition closing → prototype-sync → test-merge → compound promotion`**。理由：门禁只能在转换点校验，故回写必须发生在转换**之前**才能被拦住；原顺序下"未回写"在状态机层面不可见。
+- **新增 `tf arch scaffold`**：产出目标格式的空台账基线（含成对 marker），供 `workflow-bootstrap` B2 首次建立全局台账。`workflow-bootstrap` Step 0/1/2 相应改写——**禁止**手写 `PHYSICAL-MODEL.md` / `API-INDEX.md` / `DATABASE.md`（这四件由 arch-merge 无条件重建，手写在首次 merge 时即被整体覆盖，最坏情形是用户提供的物理模型知识彻底丢失）。
+
+### Fixed（回写链三类根因 + 17 项缺陷）
+
+**根因 Ⅰ：全局台账无唯一生产者契约**
+
+- **R1**（§102）：`workflow-bootstrap` 与 `arch-merge` 双写全局台账。修复：B2 改为委托 `tf arch scaffold`；四个生成式制品标注「由 arch-merge 维护」。**边界澄清**：`<!-- arch:current-state:begin/end -->` 之间由 arch-merge 独占，As-Is 叙述写在 marker 区**之外**。
+
+**根因 Ⅱ：回写链是「无门禁 + 无对账 + 失败不上抛」的信任区**
+
+- **R2**（§103）：`generateApiIndex` 按 `isChangeClosed` 过滤，把**正在 merge 的 change 自己排除在外**（时序自排除）→ 本 change 端点永不入索引。
+- **R3/R4**（§104）：产出量对账此前不存在；解析失配静默（`return` 无输出）。修复：对账 + **fail-closed 不写盘** + 失败上抛退出码。
+- **R7**（§107）：零聚合 change 死锁——`arch_design_decision: required` 但无聚合时被误判为解析失配，且无合法零增量表达。修复：新增 `aggregate_action: none` / `aggregate_id: 'null'` 显式声明。
+- **R8**（§108）：marker 区只投影**当前 change** 的聚合 → 多 change 并行时互相抹除。修复：全集投影（`collectAllAggregates`）。
+- **R11**（§109.4）：演进日志 upsert **非幂等**——替换正则的 `$` 在 `/m` 下是行尾而非串尾，惰性量词退化为零宽匹配，旧表体一行不删。实测 3 次运行文件 428→526→624 字节、表体 1→2→3 次，而锚行始终唯一（**"计数唯一"不足以守护幂等**，幂等断言必须下沉到内容/字节粒度）。
+
+**根因 Ⅲ：同一跨文件契约在多处各自实现**
+
+- **R5**（§105）：`extractEndpoints` 有 **6 种**形态失配（前端路由 `router.get('/x')` 被误提取、合并式单元格 `GET /path` 截断、多方法枚举、路径字符集、无方法半成品、大小写）。
+- **R6**（§106）：聚合表按**固定列位**取值 → 新增列即错位（headers 变更后列索引不对应）。
+- **R12**（§115.4）：`conflictCheck` 中有一段**手写的第二套表格解析器**（非 `parseTableRow` 调用点）——同契约双实现。
+- **R13–R17**（§115.4）：早退互锁 / 合并式截断 / `arch-snapshot.mjs` 缺 `import fs|path`（运行期 `ReferenceError`，因前三个早退分支覆盖了绝大多数场景才未暴露）/ 维度计数 / 孤儿导出。
+- **R9**（§109）：`cmd-publish` 裸 commit 卷入非预期文件。修复：pathspec + 提交后回读校验。
+- **R10**（§109.3）：脏文件白名单匹配不对称（`git status --porcelain` 对全新目录输出**目录级**条目，精确匹配必误报）。
+
+**P4/P3 复核追加（§115.5-§115.8）**
+
+- **As-Is 段端点误判为所有权**：多个 change 各自**冻结复制**同一批 As-Is 端点 → 被误判为所有权冲突（emp-auth 实测 C2/C3 共享 5 条 `/auth/*`）。已排除。
+- **端点重复声明硬阻断 → WARN**（聚合冲突仍硬阻断，二者判据区分）。
+- **失败未归属 owner（严重）**：`generateApiIndex` 扫描「当前 change + 全部已关闭 change」，原实现把**任一** change 的解析失配都算作本次 failure → **一个历史脏数据死锁所有后续 change 的 closing**（当前 change 回写已落地、门禁 PASS，但命令退出码 1；且 `arch_merge_skipped` 只豁免 guard 维度、不清除命令级 failure → 逃生通道不通）。修复：失败按 owner 分流，非本 change 的失配降级为 `[历史 change 解析异常]` WARN。
+- **change 级模板占位端点可被提取**：`templates/api.md` 的占位路径 `/api/xxx` 会被当真实端点。修复：改为 `<endpoint>` + 警告横幅。
+- **收尾顺序 8 处残留**：README / 两个 SKILL / agent description / 两处代码注释 / SKILL 锚点漂移 / `HANDOFF.md`（第 8 处，复核搜索口径未覆盖，主代理换口径重搜才命中）。`HANDOFF.md` 因全文停留 v0.30.0（计数 23+15 vs 实际 26+17）且全仓零引用，**不改顺序行、加作废横幅**——只改 3 行会造成"已同步"的假象。
+
+### Changed（行为变更，存量项目升级须知）
+
+| # | 变更 | 存量项目的表现 | 处置 |
+|---|------|--------------|------|
+| 1 | `executing→closing` 新增 `arch-merged` 门禁 | 未回写全局台账的 change **转换被拒** | 按新顺序先 `tf arch-merge` 再 `tf state transition closing`；无增量者登记 `arch_merge_skipped` + `arch_merge_skip_reason` |
+| 2 | `tf arch-merge` **fail-closed** | 「模板原样未填 + `arch_design_decision: required`」从静默产出空台账 → **FAIL** | 补实表体；确无增量则登记跳过键 |
+| 3 | `tf arch-merge` 退出码 **0 → 1** | 脚本/CI 中依赖退出码的调用方 | 失败时不再静默；历史 change 的畸形 `api.md` 已降级为 WARN，不阻断当前 change |
+
+> **豁免面**（存量不受影响）：`arch_baseline` 缺失 = 存量信号 → `arch-merged` / `arch-snapshot` 均按 legacy 豁免；`arch_design_decision` 为 `null` → 透明放行；hotfix/tweak 不挂该维度。
+
+### Tests
+
+`npm test` **871 → 893**（+22），`test:e2e` **68 → 73**（+5），frontmatter-lint 64/64。
+
+- **新增 `tests/lib/arch-parse.test.mjs`**（22 项）：6 种提取失配形态 + 表头列映射（R6）+ 路径字符集/HTTP 词表单一来源（§105.3）
+- **`tests/lib/arch-merge.test.mjs`** 追加：R8 全集投影不互抹 / R4 fail-closed 正反面（失配 FAIL ↔ 纯 DB 不误杀）/ **§115.8 失败归属 owner**（历史脏数据不得死锁当前 change）/ §115.5 冲突判据（As-Is 排除 + 端点降级 WARN + 聚合仍硬阻断）
+- **`tests/lib/guard-arch-gates.test.mjs`**（15 项）
+- **`tests/e2e/deterministic/guard-dimensions.test.mjs`** 新增 arch-merged 区块（+5）：台账无记录 FAIL / marker 区通道 PASS / 演进日志锚通道 PASS / 两档豁免
+- **`tests/e2e/helpers/fixture.mjs`** 新增共享夹具 `writeGlobalLedger`（防后续门禁测试漏打戳 `arch_baseline` → 按 legacy 豁免 → 测试**假绿**）
+
+> **重放验收**：在 emp-auth **副本**（`/tmp`，真实仓库未触碰）重放 C1/C2/C3 → 三个 change 全部完成 arch-merge（0 失败），`API-INDEX.md` 含 **33 条**三类增量端点、**零前端路由误报**。
+
+### 实施纪律（新增 P4 强制动作）
+
+**"把一段代码包进新作用域/块"时，必须逐字比对被替换区间是否夹带了控制流条件。** 本版处置「失败归属 owner」时，一次 Edit 的 `old_string` 含 `if (epSections.length > 0 && epTotal === 0 && candTotal > 0)`，`new_string` 未保留 → **"有候选即 FAIL" 无条件触发**，`tests/lib/arch-merge.test.mjs` 立即 13 项失败（含"正常 merge"）。单测是最短反馈路径。
+
+## [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 转义缺位）

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.1 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.53.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/HANDOFF.md

@@ -1,5 +1,16 @@
 # team-flow · Handoff 文档（Claude Code 继续开发用）
 
+> ## ⚠️ 本文档已作废（2026-09-10 标注，v0.53.0）
+>
+> 最后更新停留在 **2026-07-28（v0.30.0 时代）**，此后未再维护。已知失准之处至少包括：
+> skill/agent 计数（此处 23+15，实际 **26+17**）、closing 回写链顺序
+> （此处 `arch-merge → prototype-sync`，实际 **`arch-merge → state transition closing → prototype-sync → test-merge`**，v0.53.0 §110 B' 时序前移）等。
+>
+> **权威来源**：`CLAUDE.md` / `AGENTS.md` / `README.md` / `../docs/architecture-api-db-design-enhancement-v0.25.md`。
+> 本文档**仅作历史追溯**，**不得**据其执行流程——照旧顺序执行会触发 `arch-merged` 门禁拒绝（因回写未发生在状态转换之前）。
+>
+> 保留不删的理由：记录 v0.30.0 时代的插件形态与设计决策，供追溯。
+
 > 本文件用于把「team-flow 统一插件」的当前状态、设计决策、安装方式、剩余待办一次性交接清楚，
 > 以便后续在 **Claude Code** 中直接打开 `team-flow/` 目录继续开发，无需回看历史对话。
 > 最后更新：2026-07-28

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.1**。
+当前发布版本：**v0.53.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.51.1`
+> 当前版本：`v0.53.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 
@@ -113,7 +113,7 @@ Skills 命名保留其来源前缀，作为功能分组的自然标识：
   → S4 拆分验证与分发 → arch-readiness 门 → change-split-auditor 审计（必选门禁）→ 创建 change → 进入 team-flow
   → S5 全局监控（change≥2 必选）→ 跨 change 一致性 + 复利晋升 + 动态重规划
   → [复利贯穿层] 每个阶段转换点：检测→捕获→索引→注入
-  → change 完成：arch-merge → prototype-sync（顺序提交）+ 复利晋升
+  → change 完成：arch-merge → state transition closing → prototype-sync → test-merge（顺序提交）+ 复利晋升
 ```
 
 详见 `AGENTS.md`。

package/agents/release-archivist.md

@@ -1,6 +1,6 @@
 ---
 name: release-archivist
-description: 发布归档 agent——在 build-executor 完成实施之后、change 关闭之前，执行验证、产出 closing 总结并完成归档就绪（arch-merge / prototype-sync / 复利晋升）。可写型，负责归档制品。
+description: 发布归档 agent——在 build-executor 完成实施之后、change 关闭之前，执行验证、产出 closing 总结并完成归档就绪（含收尾回写链；顺序与细则以预加载 Skill 为唯一真相源）。可写型，负责归档制品。
 
 model: inherit
 color: yellow
@@ -15,7 +15,7 @@ You are an independent Release Archivist. You close out a team-flow change clean
 
 **You are the sole owner of the closing verification report and archive artifacts** (the Step-5 report, `decision-point-audit.md` inclusion, closing summary) for this change. No other agent or the orchestration layer may directly edit these. Re-verification requests MUST be routed through you via `SendMessage` resume.
 
-**Your preloaded Skill contains the detailed methodology** (Verification-Before-Completion iron law, 5-step verification, DP-6/DP-7 gates, arch-merge → prototype-sync → compound-promotion order, lightweight closure). Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver.
+**Your preloaded Skill contains the detailed methodology** (Verification-Before-Completion iron law, 5-step verification, DP-6/DP-7 gates, the mandatory write-back order, lightweight closure). Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver. **The write-back order is defined in the Skill — do not restate it here** (a duplicated order string is a drift source; v0.53.0 moved the state transition into that order, and this file had already drifted).
 
 ## Iron Law
 
@@ -51,8 +51,8 @@ summary: "..."                       # closing summary + any WARNs needing user
 **DO:**
 - Follow the preloaded Skill's 5-step verification and write-back ordering methodology
 - Run each proving command fresh and cite command + output for every claim
-- Execute write-backs sequentially: arch-merge → prototype-sync → compound promotion
-- Write your own `dp_6_*`/`dp_7_*`/`test_result` fields via `tf state set` as the Skill instructs
+- Execute write-backs **sequentially** in the order the Skill defines (see Skill — do not restate the sequence here)
+- Write ONLY the state fields the Skill authorizes via `tf state set`: your own `dp_6_*`/`dp_7_*` decision fields, plus the `arch_merge_skipped`/`arch_merge_skip_reason` skip keys when arch-merge is a genuine no-op. **`test_result` is NOT writeable by hand** — since v0.13 §50 it is recorded programmatically by `tf test record` (this file previously listed it; that was drift).
 
 **DON'T:**
 - DO NOT modify the `state` or `workflow` field of .team-flow.yaml. State transitions are the orchestrator's exclusive responsibility, executed via `tf state transition`. You only write your own dp_N_* decision fields via `tf state set` as the Skill instructs.

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.51.1`
+- Current: `v0.53.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

@@ -222,15 +222,17 @@ tf runtime guard check <change-dir> <from-state> <to-state> [--workflow full|hot
 | execution-reviews-passed | executing→closing | 有 wave 缺 pass 审查回执 → 补审查 |
 | compound-captured | executing→closing | 缺 learnings.md → `tf solutions capture` 或显式 skip |
 | arch-snapshot | executing→closing | 产品级架构快照缺失 → 补快照或物化 SKIPPED 标记 |
+| arch-merged | executing→closing | 架构增量未回写全局台账 → **先跑 `tf arch-merge <change-dir>` 再转换**（v0.53.0 B' 时序）；确无增量可回写时 `tf state set <dir> arch_merge_skipped true` + `arch_merge_skip_reason` |
 
 **设计哲学**：门禁硬，但每条都有逃生舱——存量豁免（字段缺失即视为老 change）、显式 skip+理由、`--force`/`--acknowledge-*` 参数。豁免一律留痕，可审计。
 
 ### 4.6 复利闭环——change 关闭时自动发生什么
 
-closing 阶段 release-archivist 会按**固定顺序**执行回写链：
+closing 阶段 release-archivist 会按**固定顺序**执行回写链（v0.53.0 起**状态转换插在 arch-merge 之后**——`executing→closing` 挂 `arch-merged` 门禁，未回写则转换被拒）：
 
 ```
 tf arch-merge（架构增量 → docs/architecture/ 全局当前态）
+  → tf state transition closing（状态转换；受 arch-merged 门禁校验）
   → tf prototype-sync（UX 增量 → 全局 prototype/）
   → tf test-merge（测试矩阵 → docs/test-ledger/ 全局台账）
   → tf solutions promote（learnings.md 经验 → docs/solutions/）
@@ -407,7 +409,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]
@@ -426,6 +428,7 @@ tf prototype branch <prd-vN> | tf prototype deisolate <prd-vN> [--merge]
 ```bash
 tf solutions capture|index-gen|inject|promote
 tf arch init [--mode reconstruction|design]   # 项目架构基线打戳（存量豁免键）
+tf arch scaffold                              # 全局台账脚手架（目标格式空基线，v0.53.0 §102）
 tf arch show
 tf arch precheck <change-dir> [--json]        # 架构判断门证据（signal none/weak/strong，退出码恒 0）
 tf inject <dir> [--platforms claude,cursor,...]   # 按当前状态生成 phase-guard 注入各平台

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.1",
+  "version": "0.53.0",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.51.1: auto-sync CLI version with plugin version
+# v0.53.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.51.1"
+PLUGIN_VERSION="0.53.0"
 
 # ═══════════════════════════════════════════════════════════════
 # Step 1: Auto-sync CLI version with plugin version

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.1.
+Current version: v0.53.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.1",
+  "version": "0.53.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.1",
+  "version": "0.53.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/guard/checks/arch-merged.mjs

@@ -0,0 +1,101 @@
+// scripts/guard/checks/arch-merged.mjs — arch-merged 门禁（v0.53.0，设计增强方案 v0.25 §110）
+//
+// 挂 `executing:closing`：本 change 的架构增量必须已回写到全局 docs/architecture/。
+//
+// **背景（§101.4 根因 II）**：team-flow 对「代码→测试」「specs→merge」「tasks→complete」
+// 都挂了门禁，唯独「架构增量→台账」没有——`executing:closing` 原挂 9 个维度、无 arch-merge；
+// 且 `VALID_STATES` 无 `closed`（`isChangeClosed` 的 `state === 'closed'` 是死分支），
+// **arch-merge 在状态机上没有任何锚点**。
+//
+// **B' 方案（§110.2）**：arch-merge 前移到状态转换**之前**执行，本维度即该转换的前置条件。
+// 时序：`tests/reviews 通过 → tf arch-merge → tf state transition closing → prototype-sync`。
+// 语义上可行——`executing→closing` 是一个**原子门禁**，所有维度一起 PASS 才放行，
+// 把「回写」纳入门禁校验范围不改变「验证通过后才归档」的语义。
+import fs from 'node:fs';
+import path from 'node:path';
+import { findProjectRoot, readArchState, isLegacyArch } from './arch-gate-exemptions.mjs';
+
+/**
+ * 读 change 的 .team-flow.yaml 顶层标量字段。
+ *
+ * ⚠ **未设置字段在 state 文件中序列化为字符串 `'null'` 而非 JS `null`**——这是项目
+ * 既定约定（`writeState` 用 `state.x ?? 'null'` 拼接）。`arch-design.mjs` /
+ * `compound-captured.mjs` 均显式归一化（`val === 'null' ? null : val`）。**本 check
+ * 初版漏了这一步**：test 夹具未设 `arch_design_decision` 时读到的 `'null'` 是真值，
+ * 于是「无架构增量」被误判为「需要回写」→ 门禁误 FAIL。
+ */
+function readChangeState(changeDir) {
+  const p = path.join(changeDir, '.team-flow.yaml');
+  if (!fs.existsSync(p)) return {};
+  const out = {};
+  for (const line of fs.readFileSync(p, 'utf-8').split('\n')) {
+    const m = line.match(/^(\w+):\s*(.*)$/);
+    if (m) out[m[1]] = (m[2] === 'null' || m[2] === '') ? null : m[2].trim();
+  }
+  return out;
+}
+
+/**
+ * @param {string} changeDir - change 目录路径
+ * @returns {{ pass: boolean, failures: string[] }}
+ */
+export function checkArchMerged(changeDir) {
+  const changeName = path.basename(path.resolve(changeDir).replace(/\/$/, ''));
+  const state = readChangeState(changeDir);
+
+  // ① 无架构增量 → 豁免（arch_design_decision 缺失或 skipped）
+  const decision = state.arch_design_decision;
+  if (!decision || decision === 'skipped') return { pass: true, failures: [] };
+
+  // ② 显式跳过键（§110.2 加固 iii）——与 tasks_skipped / test_matrix_skipped 同一模式。
+  //    用于 arch-merge 确为 no-op 的场景（如 architecture.md 无演进日志段且无聚合）。
+  if (state.arch_merge_skipped === 'true') {
+    console.warn(`  [WARN] arch-merged: 显式跳过（reason: ${state.arch_merge_skip_reason || '<未填写>'}）`);
+    return { pass: true, failures: [] };
+  }
+
+  // ③ legacy 项目豁免（复用 arch-gate-exemptions 唯一真相源，防判定漂移）
+  const root = findProjectRoot(changeDir);
+  if (!root) return { pass: true, failures: [] };
+  if (isLegacyArch(readArchState(root))) {
+    console.warn('  [WARN] arch-merged: 项目架构基线未建立（arch_baseline 缺失）— legacy 豁免');
+    return { pass: true, failures: [] };
+  }
+
+  const archPath = path.join(root, 'docs', 'architecture', 'ARCHITECTURE.md');
+  if (!fs.existsSync(archPath)) {
+    return {
+      pass: false,
+      failures: [`全局 docs/architecture/ARCHITECTURE.md 不存在 — 运行 tf arch-merge ${changeDir}`],
+    };
+  }
+  const content = fs.readFileSync(archPath, 'utf-8');
+
+  // 双通道判据（**缺一则门禁可能永久 FAIL 无出路**，见 §115.1 P0-2）：
+  //
+  // 通道 ①：marker 区来源列的单元格**精确等于** `change:<name>`
+  //   —— 必须按单元格精确匹配：`content.includes('change:' + name)` 会被
+  //      `change:v1-C1-other` 这类前缀相同的邻项误命中。
+  //
+  // 通道 ②：演进日志锚 `### change:<name>`
+  //   —— **为何必须有此通道**：`upsertEvolutionLog` 在 change 的 architecture.md
+  //      **没有演进日志段**时首行即 `return globalContent` 静默早退，全局永远不会出现
+  //      该锚；而零聚合 change 的 marker 区来源列也不会出现（marker 区来自已合并聚合）。
+  //      只认单通道 → 这两类 change **永久 FAIL 且重跑 arch-merge 也不会改善**。
+  const viaRegistry = content.split('\n').some(line =>
+    line.split('|').some(cell => cell.trim() === `change:${changeName}`));
+  const escaped = changeName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const viaLog = new RegExp(`^### change:${escaped}\\s*$`, 'm').test(content);
+
+  if (viaRegistry || viaLog) return { pass: true, failures: [] };
+
+  return {
+    pass: false,
+    failures: [
+      `本 change 的架构增量未回写全局台账（marker 区来源列与演进日志锚均无 change:${changeName}）`
+      + ` — 运行 tf arch-merge ${changeDir}。`
+      + `B' 时序：arch-merge 在 executing→closing 转换**之前**执行（设计增强方案 v0.25 §110.2）。`
+      + `若本 change 确无架构增量可回写，显式置 arch_merge_skipped: true + arch_merge_skip_reason。`,
+    ],
+  };
+}

package/scripts/guard/checks/arch-snapshot.mjs

@@ -1,11 +1,24 @@
 // scripts/guard/checks/arch-snapshot.mjs — 架构快照门禁（v0.35.0，v0.14 §59.4）
-// 挂 executing:closing（先于 arch-merge）：本轮迭代产品级架构快照必须已落盘（"先快照后回写"强制化）。
+// 挂 executing:closing：本轮迭代产品级架构快照必须已落盘（"先快照后回写"强制化）。
+//
+// v0.53.0 注释修正：原写「（先于 arch-merge）」。B' 方案（设计增强方案 v0.25 §110）已把
+// arch-merge 前移到本转换**之前**执行，"先于 arch-merge"不再成立。二者现同挂本转换且
+// **无数据依赖**：本 check 只读 `docs/architecture/iterations/`，而 arch-merge 全流程不触碰
+// 该目录（已逐行核对）。"先快照后回写"仍是语义前提（快照在 ARCH 阶段产出，早于整个 closing）。
 //
 // 规则：
 // - arch_baseline == null（在途/存量）→ PASS + WARN（legacy 豁免）
 // - skip 已物化（iterations/vN/SKIPPED）→ PASS
 // - iterations/<latest>/architecture.md 存在 → PASS
 // - 否则 → FAIL
+//
+// v0.53.0 §115.1 P2-5 修复：本文件使用 `join` / `existsSync` 但**从未导入**
+// `node:path` / `node:fs` → 走到兜底分支时抛 `ReferenceError`（运行期崩溃）。
+// 此前未暴露是因为前三个早退分支（legacy / skip / 有快照）覆盖了绝大多数场景；
+// 只有「非 legacy + 无 skip + 无快照」的项目才会走到第 35 行。横展核查全部 22 个
+// guard check 文件（该目录 .mjs 文件数，随本轮新增 arch-merged.mjs 由 21 增至 22），仅此一处。
+import fs from 'node:fs';
+import path from 'node:path';
 import {
   findProjectRoot, readArchState, isLegacyArch,
   findLatestIterationSnapshot, isArchSkipMaterialized, ARCH_READINESS_FAIL_HINT,
@@ -32,8 +45,8 @@ export function checkArchSnapshot(changeDir) {
   if (snap) return { pass: true, failures: [] };
 
   // v0.36.3 §63.4 在途 change 兜底：快照缺失但 change 已有增量产物 → 以 change 产物为实际态（存量升级场景）
-  const archDir = join(changeDir, 'architecture');
-  if (existsSync(archDir) && existsSync(join(archDir, 'architecture.md'))) {
+  const archDir = path.join(changeDir, 'architecture');
+  if (fs.existsSync(archDir) && fs.existsSync(path.join(archDir, 'architecture.md'))) {
     console.warn('  [WARN] arch-snapshot: 产品级快照缺失，以 change 增量产物兜底（存量升级在途 change，快照后补为 v0）');
     return { pass: true, failures: [] };
   }

package/scripts/guard/guard.mjs

@@ -18,6 +18,7 @@ import { checkTestMatrixComplete } from './checks/test-matrix-complete.mjs';
 import { checkTestMatrixReady } from './checks/test-matrix-ready.mjs';
 import { checkArchReadiness } from './checks/arch-readiness.mjs';
 import { checkArchSnapshot } from './checks/arch-snapshot.mjs';
+import { checkArchMerged } from './checks/arch-merged.mjs';
 import { checkDelegationStatus } from './checks/delegation-status.mjs';
 
 // Transition matrix: <from>:<to> → required check dimensions
@@ -38,7 +39,13 @@ const TRANSITION_CHECKS = {
   'approved-for-build:executing':   ['artifacts-exist', 'contract-fresh', 'dp-gate-passed', 'execution-plan-ready', 'test-matrix-ready'],
   // v0.35.0 (v0.14 §59.4): arch-snapshot 新增——"先快照后回写"的强制化（legacy 豁免）。
   // 仅在 full workflow 挂；hotfix/tweak 沿用 §59.4 豁免（紧急/微调不挂）。
-  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete', 'arch-snapshot', 'delegation-status'],
+  //
+  // v0.53.0（设计增强方案 v0.25 §110.2 B' 方案）：**arch-merged 新增**——把
+  // 「架构增量必须回写全局台账」从文档承诺变成机械约束。原状：该转换挂 9 维、无 arch-merge，
+  // 且 arch-merge 在状态机上无任何锚点（VALID_STATES 无 closed、closing→closed 不存在）。
+  // B' 把 arch-merge 前移到本转换**之前**，本维度即其前置条件。
+  // hotfix/tweak 沿用既有豁免口径（WORKFLOW_TRANSITION_CHECKS 各自列维度，天然不挂）。
+  'executing:closing':              ['tasks-complete', 'tests-passing', 'specs-merged', 'execution-plan-ready', 'execution-reviews-passed', 'compound-captured', 'test-matrix-complete', 'arch-snapshot', 'delegation-status', 'arch-merged'],
 
   // Debugging side-path
   'executing:debugging':            [],
@@ -189,6 +196,7 @@ async function main() {
     'test-matrix-ready': (dir) => checkTestMatrixReady(dir),
     'arch-readiness': (dir) => checkArchReadiness(dir),
     'arch-snapshot': (dir) => checkArchSnapshot(dir),
+    'arch-merged': (dir) => checkArchMerged(dir),
     'delegation-status': (dir) => checkDelegationStatus(dir),
   };