@xulthekl/team-flow 0.52.0 → 0.53.0

package/skills/prototype/SKILL.md

@@ -91,7 +91,7 @@ prototype/
 
 ## prototype-sync（change 完成回写，release-archivist 自动触发，v0.24.0 升级）
 
-> **触发机制（v0.24.0）**：prototype-sync 由 `release-archivist` closing 流程**自动触发**（`arch-merge → prototype-sync → compound promotion` 顺序执行），不再是手动 SOP。release-archivist Step 5 Report 中 `Prototype sync` 行是必填维度，未执行时 closing 报告不完整。
+> **触发机制（v0.24.0；v0.53.0 补入状态转换位次）**：prototype-sync 由 `release-archivist` closing 流程**自动触发**（`arch-merge → state transition closing → prototype-sync → compound promotion` 顺序执行），不再是手动 SOP。release-archivist Step 5 Report 中 `Prototype sync` 行是必填维度，未执行时 closing 报告不完整。
 >
 > **独立调用**：仍可独立调用（如 change 中途需要预同步），但标准路径是 closing 自动触发。
 
@@ -99,7 +99,7 @@ prototype/
 2. **派 `prototype-builder`（修正/演进模式）**把增量合并进全局 `prototype/`（pages/components/assets/flow.md）——主代理不直接写原型 HTML。
 3. 若涉及设计系统迭代，调用 `/team-flow:design-system`（iterate 模式）合并进 `.team-flow/design-system/` 并记变更履历。
 4. 人工确认增量无误。
-5. **顺序提交**：`arch-merge` → `prototype-sync`（同一 change closing 内）。
+5. **顺序提交**：`arch-merge` → `state transition closing` → `prototype-sync`（同一 change closing 内）。**状态转换必须在 arch-merge 之后、prototype-sync 之前**（v0.53.0 §110 B' 时序前移：`executing→closing` 挂 `arch-merged` 门禁，未回写则转换被拒）。
 
 ## 脚手架
 新建项目：`cp -r references/prototype-scaffold/ <project>/prototype/`，再按 `.team-flow/design-system/` 的设计系统填 token（缺设计系统先用 `/team-flow:design-system` 创建）。

package/skills/release-archivist/SKILL.md

@@ -118,7 +118,7 @@ Check for files modified outside scope fence, new dependencies not in design. Un
 
 ## Final Checks
 
-**⛔ 状态字段禁写（v0.30.0 + v0.13 §50）**：仅写本 skill 的 `dp_6_*`/`dp_7_*` 决策字段；测试证据经 `tf test record` 程序化写入（不再手工 set `test_result`）；**MUST NOT** 修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段——closing 转换由主代理经 `tf state transition` 执行（来源：workflow-feedback 2026-08-01）。
+**⛔ 状态字段禁写（v0.30.0 + v0.13 §50；v0.53.0 增补跳过键）**：仅写本 skill 的 `dp_6_*`/`dp_7_*` 决策字段 + `arch_merge_skipped`/`arch_merge_skip_reason` 跳过键（后者见 `### ① Architecture Merge` 的 no-op 登记指引）；测试证据经 `tf test record` 程序化写入（不再手工 set `test_result`）；**MUST NOT** 修改 `.team-flow.yaml` 的 `state`/`workflow` 核心字段——closing 转换由主代理经 `tf state transition` 执行（来源：workflow-feedback 2026-08-01）。
 
 - Tests passing? (cite command and output)
 - All batches complete? (cite batch status)
@@ -149,13 +149,27 @@ If implementation diverged from the contract, return to `bridging` before closur
 
 ## Post-Verification
 
-Run `tf state transition <change-dir> closing`. If delta specs exist, route to `spec-merger`.
+### ⚠ 执行顺序（v0.53.0 §110 B' 时序前移 — MUST）
+
+```
+① tf arch-merge <change-dir>              ← 架构增量回写全局台账
+② tf state transition <change-dir> closing
+③ tf prototype-sync <change-dir>
+④ tf test-merge <change-dir>
+⑤ tf solutions promote（compound promotion）
+```
+
+（各步详细说明见下方对应节标题的 ①–⑤ 编号。）
+
+> **本块是全流程中该顺序的【唯一真相源】**（v0.53.0 §115.10）：②③ 两节及「阶段产物同步门禁点」原先各自复述同一顺序串（本文件内共 4 处），是既有的漂移源——`agents/release-archivist.md` 已明文禁止复述，本文件却复述了 4 次。现各处改为指向本块。
+>
+> **为何 ① 必须在 ② 之前**（v0.53.0 变更，务必遵守）：`executing→closing` 现挂 **`arch-merged` 门禁维度**——转换时校验全局台账已含本 change 增量。**未回写则转换被拒**。完整论证（含与 `arch-snapshot` 的无数据依赖关系）见 `references/closing-procedures.md`。
 
-**架构快照门禁（arch-snapshot，v0.36.0 / v0.36.3）**：`executing→closing` 挂 `arch-snapshot` 维度——本轮迭代产品级架构快照 `iterations/vN/architecture.md` 必须已落盘（"先快照后回写"强制化）。**FAIL 升级路径**：回 orchestrator 的 ARCH 阶段补快照；存量升级在途 change（快照缺失但 change 有增量产物）→ WARN 兜底放行；`arch_baseline` 缺失 → WARN 不阻断。hotfix/tweak 豁免（不挂该维度）。判定逻辑见 `scripts/guard/checks/arch-gate-exemptions.mjs`。
+**架构快照门禁（arch-snapshot，v0.36.0 / v0.36.3）**：本轮迭代产品级架构快照 `iterations/vN/architecture.md` 必须已落盘（"先快照后回写"强制化）。**FAIL 升级路径**：回 orchestrator 的 ARCH 阶段补快照；存量升级在途 change（快照缺失但 change 有增量产物）→ WARN 兜底放行；`arch_baseline` 缺失 → WARN 不阻断。hotfix/tweak 豁免（不挂该维度）。判定逻辑见 `scripts/guard/checks/arch-gate-exemptions.mjs`。
 
-### Architecture Merge (v0.10 §28-§31) — MUST run first
+### ① Architecture Merge (v0.10 §28-§31) — MUST run first
 
-Merge change-level architecture artifacts to the global `docs/architecture/` baseline **before** any other post-verification step:
+Merge change-level architecture artifacts to the global `docs/architecture/` baseline **before** the state transition and before any other post-verification step:
 
 ```bash
 tf arch-merge <change-dir>
@@ -163,23 +177,34 @@ tf arch-merge <change-dir>
 
 This merges `architecture/{architecture,database,api}.md` and `architecture/sql/` into the global architecture docs. Skip silently when `architecture/` does not exist (architecture-design was `skipped`) — 前置判据见 `## Lightweight Closure > 回写链前置判据`（v0.22 §87：先判断再决定是否执行命令）。
 
-**Execution order (mandatory, v0.12 §43.4)**: `arch-merge` → `prototype-sync` → `test-merge` → `compound promotion`. Do not parallelise — global docs must not be in a half-updated state.
+**命令输出即是证据**：`arch-merge` 现在会汇总 `[WARN]` / `[FAIL]` 并可能以非零退出码结束。**有 `[FAIL]` 行时必须先解决再转换**（典型：`端点章节表有 N 行候选但 0 条提取——api.md 表格形态失配`）。若命令确为 no-op（无架构增量可回写），用显式跳过键登记：
+
+```bash
+tf state set <change-dir> arch_merge_skipped true
+tf state set <change-dir> arch_merge_skip_reason "<理由>"
+```
+
+### ② State Transition
+
+Run `tf state transition <change-dir> closing`. If delta specs exist, route to `spec-merger`.
+
+**顺序（MUST）**：见 `### ⚠ 执行顺序` 的 ①–⑤（**本步是 ②**，前置 ① 已完成）。不得并行——全局文档不得处于半更新态。
 
-### Prototype Sync (v0.5)
+### ③ Prototype Sync (v0.5)
 
-After `arch-merge` completes, run prototype-sync to merge UX deltas back to the global prototype:
+After `arch-merge` (①) completes **and the state transition to `closing` (②) has been run**, run prototype-sync to merge UX deltas back to the global prototype:
 
 ```bash
 tf prototype-sync <change-dir>
 ```
 
-**Write-back order (mandatory, v0.12 §43.4)**: `arch-merge` → `prototype-sync` → `test-merge` → `compound promotion` must be executed **sequentially** within the same change closing. Do not run them in parallel — the global `docs/architecture/`, `prototype/`, and `docs/test-ledger/` must not be in a half-updated state when the next change grounds on them.
+**顺序（MUST）**：见 `### ⚠ 执行顺序` 的 ①–⑤（**本步是 ③**，①② 已完成）。同一 change closing 内**顺序执行**，不得并行——`docs/architecture/` / `prototype/` / `docs/test-ledger/` 不得处于半更新态，否则下一个 change 会以半态为基。
 
 If `prototype-sync` reports conflicts, list them in the closing summary and flag for manual resolution. Do not block closing on prototype-sync conflicts (advisory level).
 
 **Execution verification（v0.24.0）**：`prototype-sync` 命令执行后，检查其 stdout 输出确认合并完成（输出含 `merged`/`no UX delta`/`conflicts` 之一）。若命令未执行或执行失败，Step 5 Report 的 `Prototype sync` 行必须标注 `SKIPPED` 或 `FAILED`，并在 closing summary 中说明原因。**禁止在 prototype-sync 未执行时将 Prototype sync 行标注为已完成**。
 
-### Test Merge (v0.12 §43)
+### ④ Test Merge (v0.12 §43)
 
 After `prototype-sync` completes, run test-merge to write test matrix results back to the global test ledger:
 
@@ -197,42 +222,25 @@ Skip silently when `test-matrix.md` does not exist (legacy change or test_matrix
 
 **Execution verification**: check stdout output for `test-merge complete` confirmation. If the command did not execute or failed, Step 5 Report's `Test Matrix` row (from Step 2b) must note the reason.
 
-### Compound Promotion (v0.5)
+### ⑤ Compound Promotion (v0.5)
 
-During closing, promote change-level learnings to the global solutions library:
+Promote change-level learnings to the global solutions library:
 
 ```bash
 tf solutions promote <change-dir>
 ```
 
-This checks the change's `learnings.md` (change root; v0.49.0 §83.3.5 path unification) for entries meeting promotion criteria:
-- severity ≥ medium AND type = pitfall/pattern → promote to global `docs/solutions/`
-- domain+type matches existing global entry → mark as "confirmed pattern", upgrade severity (low → medium → high → critical)
-
-Valid `severity` values: `critical` | `high` | `medium` | `low` (ordered; lowercase, case-sensitive; v0.23 §91 — the order is defined once in `scripts/lib/severity.mjs`).
-
-Report promotion results in the closing summary. Promotion is advisory — failures do not block closing.
-
-### Compound Capture Check (v0.5；v0.49.0 §83.3.5 明确写入方)
-
-Before finalizing the closing, check if this change produced any learnable moments:
+读取 change 根目录的 `learnings.md`（v0.49.0 §83.3.5 路径统一）——`severity ≥ medium` 且 `type = pitfall|pattern` 者晋升全局 `docs/solutions/`；命中既有条目则标记 confirmed pattern 并升级 severity。severity 序 `critical > high > medium > low` 定义在 `scripts/lib/severity.mjs`（v0.23 §91，单一来源）。
 
-- Did the change trigger any mandatory rewind (re-specify, re-bridge)?
-- Did bug-investigator find a recurring issue (same root cause as a prior change)?
-- Did scope expand beyond the original proposal?
-- Did execution-contract drift from proposal?
+**Compound Capture Check（v0.5）**：closing 前自检本 change 是否产生了可沉淀的经验（强制回退 / 复发根因 / 范围外扩 / 契约漂移）；有则写入 change 根的 `learnings.md`，每条 `## <title>` 带 frontmatter（`phase`/`domain`/`type`/`severity`/`date`）。该文件正是 `compound-captured` guard 检查、`tf solutions promote` 读取的对象。
 
-If any of the above occurred, **write them to the change's `learnings.md` (change root)** — one `## <title>` entry per learning, each carrying a frontmatter block (`phase` / `domain` / `type` / `severity` / `date`). Format reference: `tf runtime asset read templates/learnings.md`. This is the file the `compound-captured` guard checks and `tf solutions promote` reads; entries without frontmatter are skipped by promote (reason listed in its output).
-
-`tf solutions capture` writes to global `docs/solutions/` — it does **not** create `learnings.md`. Use it only for product-level learnings that belong directly in the global library.
-
-This check is advisory — skip silently if no learnable moments are detected.
-
-> 详细收尾流程（Prototype Sync / Compound Promotion / Compound Capture / Worktree Deisolation / Code Landing）见 `references/closing-procedures.md`。
+> **本节的展开版（条目质量要求、`tf solutions capture` 与 `learnings.md` 的分工、Prototype Sync / Worktree Deisolation / Code Landing 全流程）见 `references/closing-procedures.md`**——该处为超集，本节不再重复（v0.53.0 §115.10：同名节曾两处各自维护，属根因 Ⅲ 的同一类漂移）。
 
 ### 阶段产物同步门禁点（v0.37.0 §68.2 G5）
 
-回写链（arch-merge → prototype-sync → test-merge → compound promotion）全部完成后、`tf state transition closing` 之前，**阻塞确认**（AskUserQuestion）是否同步 change 实施结果（团队协作：落地结果是团队最需要看的内容）：
+回写链（顺序见 `### ⚠ 执行顺序` 的 ①–⑤）**全部完成后**，**阻塞确认**（AskUserQuestion）是否同步 change 实施结果（团队协作：落地结果是团队最需要看的内容）：
+
+> **v0.53.0 时序说明**：本门禁点原先表述为"回写链全部完成后、`tf state transition closing` **之前**"——那是旧顺序（转换在最后）。B' 方案已把状态转换前移到 ②，故本门禁点改为以「回写链**全部完成后**」为准，**不再对转换位置附加约束**。二者不冲突：本门禁只关心"实施结果是否同步"，与转换先后无关。
 - **A 提交并推送**：`tf publish --changes <change-dir> --push`
 - **B 仅提交不推送**：`tf publish --changes <change-dir>`（arch-merge/test-merge 已自动 commit，此步补 push）
 - **C 暂不同步**：继续 closing，后续可补
@@ -268,7 +276,9 @@ This check is advisory — skip if the user declines. If the user reports issues
 
 Verify files exist and are non-empty, run `node --check` on code files, skip 5-step verification. Still record DP-6 and DP-7.
 
-**回写链前置判据（v0.22 §87）**：先按下表判断适用性，**不适用则不执行命令**（v0.22 实测：逐项跑完才知道不适用，占 release-archivist 80% 耗时）。本表 4 行判据**仅在 Lightweight Closure 适用**；其中 arch-merge 与 test-merge 两行的 "Skip silently" 见 `### Architecture Merge`（:164 正文句）与 `### Test Merge`（:196 正文句）。
+**回写链前置判据（v0.22 §87）**：先按下表判断适用性，**不适用则不执行命令**（v0.22 实测：逐项跑完才知道不适用，占 release-archivist 80% 耗时）。本表 4 行判据**仅在 Lightweight Closure 适用**；其中 arch-merge 与 test-merge 两行的 "Skip silently" 见 `### ① Architecture Merge` 与 `### ④ Test Merge` 两节各自的正文句。
+
+> **v0.53.0 修正**：此处原用行号引用（`（:164 正文句）`/`（:196 正文句）`），本次改动插入段落使其失效。**行号引用在密集改动期必然漂移，已改为按标题引用**——同轮 `docs/architecture-api-db-design-enhancement-v0.25.md` 亦把 45 处行号引用全量改为符号引用。
 
 | 回写项 | 前置判据 | 不满足时登记 |
 |---|---|---|

package/skills/release-archivist/references/closing-procedures.md

@@ -4,13 +4,20 @@
 
 ## Prototype Sync (v0.5)
 
-After `arch-merge` completes, run prototype-sync to merge UX deltas back to the global prototype:
+After `arch-merge` completes **and the state transition to `closing` has been performed**, run prototype-sync to merge UX deltas back to the global prototype:
 
 ```bash
 tf prototype-sync <change-dir>
 ```
 
-**Write-back order (mandatory)**: `arch-merge` → `prototype-sync` → `compound promotion` must be executed **sequentially** within the same change closing. Do not run them in parallel — the global `docs/architecture/` and `prototype/` must not be in a half-updated state when the next change grounds on them.
+**Write-back order (mandatory；v0.53.0 增补状态转换位次)**: `arch-merge` → `state transition closing` → `prototype-sync` → `test-merge` → `compound promotion` must be executed **sequentially** within the same change closing. Do not run them in parallel — the global `docs/architecture/` and `prototype/` must not be in a half-updated state when the next change grounds on them.
+
+> **为何状态转换插在 arch-merge 之后**（v0.53.0 §110 B' 时序前移，完整论证）
+>
+> ① **门禁只能在转换点校验**：`executing→closing` 现挂 `arch-merged` guard 维度——转换时校验全局 `docs/architecture/ARCHITECTURE.md` 已含本 change 增量（marker 区来源列 `change:<name>` **或** 演进日志锚 `### change:<name>`，双通道）。**未回写则转换被拒**。故 arch-merge 必须先于转换执行。
+> ② **原顺序下"未回写"在状态机层面不可见**：旧序把 arch-merge 放在转换**之后**，而 `VALID_STATES` 无 `closed`、`closing→closed` 转换不存在 → arch-merge 在状态机上**没有任何锚点**，其成败无门禁考核。这是"架构变更必须合并进台账"这条原则长期停留在**文档承诺**而非**代码强制**的机制原因。
+> ③ **与 `arch-snapshot` 不冲突**：两者同挂本转换（`arch-snapshot` 是 v0.36.0 的"先快照后回写"），但**维度之间无数据依赖**——`arch-snapshot` 只读 `docs/architecture/iterations/`，`arch-merge` 全流程不触碰该目录（已逐行核对）。"先快照后回写"仍是语义前提（快照在 ARCH 阶段产出，早于整个 closing）。
+> ④ **逃生通道**：若本 change 确无架构增量可回写，登记 `tf state set <change-dir> arch_merge_skipped true` + `arch_merge_skip_reason "<理由>"`，该维度即豁免。注意：跳过键**只豁免门禁维度**，不改变 `tf arch-merge` 命令自身的退出码——命令的失败按 **owner 归属**判定，非本 change 的解析失配只报 WARN，不会阻断你（v0.53.0 §115.8）。
 
 If `prototype-sync` reports conflicts, list them in the closing summary and flag for manual resolution. Do not block closing on prototype-sync conflicts (advisory level).
 
@@ -62,11 +69,14 @@ tf state set <change-dir> dp_6_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 
 If FAIL, do NOT proceed to DP-7. Route back or ask about abandonment.
 
-After PASS, also record the verification gate:
+After PASS, also record the verification gate **程序化写入**（v0.53.0 修正：本处原写 `tf state set <change-dir> test_result pass`，与同轮修正的 `SKILL.md`「不再手工 set `test_result`」及 CLI 实测互相矛盾——CLI 直接拒绝：`⛔ 'test_result' 不再支持手工 set(v0.13 §50)`）：
+
 ```bash
-tf state set <change-dir> test_result pass
+tf test record <change-dir> --from <runner-output-file>
 ```
 
+（`test_result` 已移出 `SETTABLE_FIELDS`，`tests-passing` 门禁只认 `tf test record` 写入的程序化证据。DP-6 段此前的 `dp_6_result` 只是决策点记录，**不是**放行凭证。）
+
 ## DP-7 (Archive Confirmation)
 
 ```bash

package/skills/workflow-bootstrap/SKILL.md

@@ -107,38 +107,47 @@ Do NOT invoke for:
 **B2 成果物导入（v0.23.0 新增，v0.24.0 模板初始化补强）**：
 
 ```
-Step 0: 目录+模板初始化（v0.24.0 新增）
-  ├── mkdir -p docs/architecture/
-  ├── 从 ${CLAUDE_PLUGIN_ROOT}/skills/architecture-design/templates/ 复制模板：
-  │     architecture.md → docs/architecture/ARCHITECTURE.md
-  │     database.md     → docs/architecture/DATABASE.md
-  │     physical-model.md → docs/architecture/PHYSICAL-MODEL.md
-  │     api.md          → docs/architecture/API-INDEX.md
-  │     index.md        → docs/architecture/INDEX.md
+Step 0: 全局台账脚手架（v0.24.0 新增；v0.53.0 修正）
+  ├── bash: tf arch scaffold --project-root <根>
+  │     复用 arch-merge 的生成器产出**目标格式**的空基线（同源，构造上消除格式漂移）
   └── 已存在的文件不覆盖（只补缺失）
 
+  ⛔ **禁止从 skills/architecture-design/templates/ 复制模板**（v0.53.0 §102 R1 废止）：
+     原做法把 **change 级模板** 复制成 **全局台账制品**（`api.md → API-INDEX.md` 等 5 处），
+     而 arch-merge 把这 5 个路径定义为 `generated, do not edit` 的生成式产物——两类写入方
+     语义互斥且互不知情。实测后果：DATABASE / PHYSICAL-MODEL / INDEX 因无条件重建被覆盖，
+     而 `ARCHITECTURE.md` / `API-INDEX.md` **永久卡在模板态**；其中 `API-INDEX.md` 模板自带
+     的 4 条 `/api/xxx` 占位行使扫描非空，**连"空结果拒绝覆盖"保护都不触发**，
+     `updateIndex` 还把这 4 行统计成 `端点数量: 4` 写进 INDEX.md。
+     详见 team-flow-workspace/docs/architecture-api-db-design-enhancement-v0.25.md §101.3 / §102.2
+
+  ⛔ **B2 不得直接写生成式制品**（v0.53.0 §115.6 横展）：`PHYSICAL-MODEL.md` / `DATABASE.md` /
+     `API-INDEX.md` / `INDEX.md` 四个由 arch-merge **无条件重建**——bootstrap 手写的内容在
+     该 change 首次 arch-merge 时即被整体覆盖（无 DDL 时 PHYSICAL-MODEL 会被改写为"暂无物理模型"，
+     **用户提供的知识丢失**）。As-Is 叙述的唯一载体是 `docs/architecture/baseline.md`。
+
 Step 1: 询问用户是否有既有成果物
   ├── 有 SQL DDL 脚本 → 导入到 docs/architecture/schema-baseline.sql
-  ├── 有物理模型文档 → 转换为 docs/architecture/PHYSICAL-MODEL.md（对齐标准格式）
-  ├── 有 API 文档/Swagger 导出 → 提取端点生成 docs/architecture/API-INDEX.md
+  │     （PHYSICAL-MODEL.md / DATABASE.md 由 arch-merge 从该文件生成，B2 不直接写）
+  ├── 有物理模型文档 → 内容并入 docs/architecture/baseline.md（B2 的 As-Is 叙述载体）
+  ├── 有 API 文档/Swagger 导出 → 端点清单写入 baseline.md §5（全局 API 表面基线）
   └── 无既有成果物 → Step 2 兜底
 
 Step 2: 确定性提取（兜底）
   ├── recon-probe.sh DDL 提取能力（v0.24.0 已实现：SQL 文件 / Java Entity / 占位）
   │   bash ${CLAUDE_PLUGIN_ROOT}/skills/workflow-bootstrap/scripts/recon-probe.sh --root <根> --ddl-out docs/architecture/schema-baseline.sql
-  ├── 从 schema-baseline.sql 反向生成 PHYSICAL-MODEL.md
-  └── 扫描 Controller/Router 类 → 生成 API-INDEX.md
+  ├── 扫描 Controller/Router 类 → 端点清单并入 baseline.md §5
+  └── （PHYSICAL-MODEL / DATABASE / API-INDEX / INDEX 由 `tf arch-merge` 维护，bootstrap 不产出）
 
 优先级原则：用户既有成果物 > 确定性提取 > LLM 推断
 ```
 
 产出：
-- `docs/architecture/ARCHITECTURE.md` — 分层、模块边界、技术选型（瘦锚点格式）
-- `docs/architecture/DATABASE.md` — 数据模型（如适用）
-- `docs/architecture/PHYSICAL-MODEL.md` — 物理模型（v0.23.0 新增）
-- `docs/architecture/schema-baseline.sql` — DDL 基线脚本（v0.23.0 新增）
-- `docs/architecture/API-INDEX.md` — API 端点索引（v0.23.0 新增）
-- `docs/architecture/INDEX.md` — 架构文档索引（v0.23.0 新增）
+- `docs/architecture/baseline.md` — **As-Is 架构基线（B2 的主要产物）**：分层、模块边界、技术选型、既有 API 清单
+- `docs/architecture/ARCHITECTURE.md` — 骨架由 `tf arch scaffold` 建；**As-Is 叙述写在 marker 区之外**，
+  `<!-- arch:current-state:begin/end -->` 之间由 arch-merge 独占维护（v0.53.0 §115.6 澄清）
+- `docs/architecture/schema-baseline.sql` — DDL 基线脚本（B2 导入；后续由 arch-merge 幂等追加）
+- `docs/architecture/{PHYSICAL-MODEL,DATABASE,API-INDEX,INDEX}.md` — **生成式，由 arch-merge 维护，B2 不写**
 - `docs/architecture/<bc>/` — 每个有界上下文的目录（如能识别）
 
 **轻量 vs 完整**：

package/skills/workflow-orchestrator/references/state-model.md

@@ -113,6 +113,9 @@ phases:
 | 产品级评审门 | ARCH→S3（2026-08-19：ARCH 上移 S3 前，原 ARCH→S4） | architecture-reviewer product 视角 PASS | skip 时仍要物化标记 |
 | arch-readiness | exploring:specifying（guard 存在性）+ S4 拆分（LLM 覆盖校验） | iterations/vN/ 快照覆盖 change 触及的 BC | arch_baseline 缺失 → WARN 不 FAIL |
 | arch-snapshot | executing→closing | 本轮快照已落盘 | 在途 change legacy 豁免 |
+| arch-merged | executing→closing（v0.53.0 新增） | 本 change 架构增量已回写全局 `docs/architecture/ARCHITECTURE.md`（marker 区来源列 `change:<name>` **或** 演进日志锚 `### change:<name>`，任一命中即 PASS） | `arch_design_decision` 缺失/skipped 豁免；`arch_baseline` 缺失 legacy 豁免；`arch_merge_skipped` 显式跳过键 |
+
+> **arch-merged 的时序前提（v0.53.0 §110 B'）**：arch-merge 需在该转换**之前**执行，否则转换被拒。详细顺序见 `team-flow/skills/release-archivist/SKILL.md` 的 `## Post-Verification`。
 
 ## arch_baseline 豁免键（v0.35.0 新增）