@xulthekl/team-flow 0.52.0 → 0.54.0

package/skills/prototype/references/orchestration-flow.md

@@ -20,7 +20,7 @@
 派发插件 agent `prototype-env-scout`（只读，tools 硬限 Read/Bash/Grep/Glob），传入：PRD 路径、config 的 `prototype.designSystem`/`prototype.entry`、当前 git 分支。简报写在 response，主代理按需落盘。
 
 子代理探查并产出环境简报：
-- **设计系统现状**：`design-system.md` 是否存在？9 段 schema 完整度？缺失哪些段？
+- **设计系统现状**：`.team-flow/design-system/` 是否存在（base.md + 端变体）？**合并后** 9 段 schema 完整度？`primer.md` 是否存在且 digest 未过期？契约表组件数分档（<10 / 10-14 / ≥15）？
 - **原型仓库分支**：当前分支、是否已有 `prototype/`、与 PRD 版本分支是否对齐
 - **PRD 版本**：`iteration_version`、冻结状态、UI 功能点清单（§4/§7）
 - **已有页面**：现有 prototype/ 页面/组件清单（迭代时）
@@ -50,7 +50,7 @@ LT 确认后进入 ③。**confirmed_plan 序列化**：将 scout 简报的选
 
 ## 步骤 ③ 原型绘制（子代理）
 
-派发插件 agent `prototype-builder`（有 Write），传入：已确认的原型方案（含选定方向）、`design-system.md` 路径、目标分支/版本、PRD 路径。
+派发插件 agent `prototype-builder`（有 Write），传入：已确认的原型方案（含选定方向）、`design_system_path`（`.team-flow/design-system/<variant>.md`，与 base.md 合并渲染）、`variant`、`prototype_root`、目标分支/版本、`prd_path`、`mode: default`（showcase 模式见 builder-methodology「Showcase 模式」——该模式豁免 `confirmed_plan`/`prd_path`）。
 
 **⛔ 子代理 ID 记录（v0.29.1，必须执行）**：dispatch 后**立即记录**子代理 ID，后续 ⑤ 循环修正和 ⑥ 人工评审调整**必须通过此 ID 恢复子代理**，不得启动新子代理：
 ```
@@ -58,7 +58,7 @@ builder_agent_id = <agentId>    # ③ dispatch 返回
 reviewer_agent_id = <agentId>   # ④ dispatch 返回
 ```
 
-**prompt 组装顺序契约（v0.18.0, v0.24.0 扩展）**：`design-system.md → references/template.html → references/layouts.md → references/checklist.md → references/craft/（按页面类型选择注入）→ references/interactive-prototype.md（按需）→ references/wireframe.md（按需）→ PRD`。
+**prompt 组装顺序契约（v0.18.0, v0.24.0 扩展）**：`.team-flow/design-system/`（base + 变体）→ references/template.html → references/layouts.md → references/checklist.md → references/craft/（按页面类型选择注入）→ references/interactive-prototype.md（按需）→ references/wireframe.md（按需）→ PRD`。
 
 craft 注入策略：仪表盘→laws-of-ux+state-coverage；表单→state-coverage+accessibility-baseline；列表→typography-hierarchy；通用→anti-ai-slop（始终注入）。
 
@@ -107,6 +107,15 @@ agent 直接写审查报告到 `requirement/vN/prototype-auto-review.md`。
 - **PRD 有问题** → 回 orchestrator S2 修订 PRD（**vN 内修订 + 变更履历，非升版**；见 feedback-loops 设计）→ PRD 更新后再回 ① 更新原型。**独立调用 fallback**（非 orchestrator 触发时）：无 S2 可回，直接提示 LT 修订 `requirement/vN/prd.md` 后重入本 skill。
 - **原型需调整**（美观/体验/品牌/信息密度等自动评审查不到的维度）→ **⛔ 必须通过 SendMessage 恢复原 prototype-builder 实施调整**（`SendMessage(to: builder_agent_id, message: "用户评审反馈：{调整意见}。请修改原型。")`），修改后 SendMessage 恢复原 prototype-reviewer 重新评审。**禁止启动新子代理**（唯一例外：SendMessage 恢复失败时的 fallback）
 - **通过** → 冻结：PRD frontmatter `frozen: true`（frozen_downstream），prototype 定版
+- **设计系统增量确认（v0.54.0，新增分支）**：若 builder handoff 的 `outstanding_questions` 含 `ds_increment` 条目（`missing_component` / `outdated_token` / `new_variant`），在本次 AskUserQuestion 中**并入**呈现：
+
+  > 「原型绘制中发现 N 项设计系统增量：① {描述}（{workaround}） ② … — [全部确认 | 逐项确认 | 暂不处理]」
+
+  - **全部确认 / 逐项确认** → 主代理调 `/team-flow:design-system`（iterate 模式）传入确认项。
+    - **时序约束**：iterate 一律**延迟到 builder 任务终态交接后**执行（避免绘制中途 primer 变更导致产出与白名单版本不一致）
+    - **并发提示**：iterate 前检查活跃 change（`${CLAUDE_PLUGIN_ROOT}/scripts/lib/state-loader.mjs`）→ 提示"本次设计系统变更会影响进行中的 change: X/Y"
+  - **暂不处理** → 由 **design-system skill**（唯一写者）追加到 `.team-flow/design-system/pending.md`；条目格式 `{描述} | 来源: <change-id 或 s2-prototype> | 时间: <ISO>`
+  - **不追溯重构**：已冻结原型不自动重绘——workaround 保留至该页下次进入绘制时替换
 
 ## 子代理阻断处理（§18.1）
 

package/skills/prototype/references/prototype-scaffold/assets/design-tokens.css

@@ -1,5 +1,5 @@
 :root{
-  /* A1-identity：由 design-system.md 渲染覆盖，此处为骨架占位 */
+  /* A1-identity：由 .team-flow/design-system/ 渲染覆盖，此处为骨架占位 */
   --color-primary: #c96442;   /* 占位，渲染时替换为品牌主色 */
   --color-neutral-900: #1a1916;
   --bg: #fafaf7; --surface: #ffffff; --fg: #1a1916; --muted: #6b6964; --border: #e8e5df;
@@ -15,5 +15,5 @@
   --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px;
   --radius-1: 4px; --radius-2: 8px;
   --font-base: 16px;
-  /* 由 design-system.md 渲染；修改走 design-system，不在此硬编码新值 */
+  /* 由 .team-flow/design-system/ 渲染；修改走 design-system，不在此硬编码新值 */
 }

package/skills/prototype/references/template.html

@@ -1,4 +1,4 @@
-<!-- 种子模板（v0.18.0）：builder 从此模板组合，不从零写 CSS。token 由 design-system.md 渲染覆盖。 -->
+<!-- 种子模板（v0.18.0）：builder 从此模板组合，不从零写 CSS。token 由 .team-flow/design-system/ 渲染覆盖。 -->
 <!-- 零外部依赖、可离线：CSS 进 <style>、JS 进 <script>，无 CDN / 外部字体 / 外部脚本。 -->
 <!doctype html>
 <html lang="zh-CN" data-theme="light" data-density="comfortable">
@@ -8,16 +8,16 @@
 <title>team-flow prototype · seed template</title>
 <style>
 /* ============================================================
-   TOKENS — 由 design-system.md 渲染覆盖，禁止在此硬编码新值。
+   TOKENS — 由 .team-flow/design-system/ 渲染覆盖，禁止在此硬编码新值。
    占位默认值为「中性陶土」基调（非 indigo），保证模板离线可渲染。
    ============================================================ */
 :root{
-  /* —— 品牌/中性色（design-system.md 覆盖位）—— */
-  --color-primary: #c96442;        /* 由 design-system.md 渲染覆盖 */
-  --color-neutral-900: #1a1916;    /* 由 design-system.md 渲染覆盖 */
+  /* —— 品牌/中性色（.team-flow/design-system/ 覆盖位）—— */
+  --color-primary: #c96442;        /* 由 .team-flow/design-system/ 渲染覆盖 */
+  --color-neutral-900: #1a1916;    /* 由 .team-flow/design-system/ 渲染覆盖 */
 
   /* —— 单一 accent：每屏 ≤2 处 —— */
-  --accent: #c96442;               /* 由 design-system.md 渲染覆盖（terracotta 中性暖色占位） */
+  --accent: #c96442;               /* 由 .team-flow/design-system/ 渲染覆盖（terracotta 中性暖色占位） */
   --accent-hover:  color-mix(in oklab, var(--accent), black 8%);
   --accent-active: color-mix(in oklab, var(--accent), black 14%);
   --accent-soft:   color-mix(in oklab, var(--accent), transparent 86%);
@@ -32,8 +32,8 @@
   --border: #e8e5df;
 
   /* —— 字体（系统栈，零外部字体）—— */
-  --font-display: ui-sans-serif, 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif; /* 由 design-system.md 渲染覆盖 */
-  --font-body:    ui-sans-serif, 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif; /* 由 design-system.md 渲染覆盖 */
+  --font-display: ui-sans-serif, 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif; /* 由 .team-flow/design-system/ 渲染覆盖 */
+  --font-body:    ui-sans-serif, 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif; /* 由 .team-flow/design-system/ 渲染覆盖 */
   --font-mono:    ui-monospace, 'JetBrains Mono', monospace;
 
   /* —— 字号阶梯（type scale）—— */
@@ -369,7 +369,7 @@ code{ font-family: var(--font-mono); font-size: 0.9em; }
     <div class="container hero-center">
       <p class="eyebrow">team-flow · seed template</p>
       <h1>从种子模板组合页面，不从零写 CSS</h1>
-      <p class="lead">所有 section 直接落入 main，token 由 design-system.md 渲染覆盖，零外部依赖、可离线。</p>
+      <p class="lead">所有 section 直接落入 main，token 由 .team-flow/design-system/ 渲染覆盖，零外部依赖、可离线。</p>
       <div class="hero-cta">
         <a class="btn btn-primary" href="#content">主操作</a>
         <a class="btn btn-secondary" href="#content">次要操作</a>
@@ -383,7 +383,7 @@ code{ font-family: var(--font-mono); font-size: 0.9em; }
 <footer class="pagefoot" data-testid="P-00-pagefoot">
   <div class="container row-between">
     <span>© team-flow prototype</span>
-    <span class="meta">由 seed template (v0.18.0) 组合 · token 由 design-system.md 渲染</span>
+    <span class="meta">由 seed template (v0.18.0) 组合 · token 由 .team-flow/design-system/ 渲染</span>
   </div>
 </footer>
 

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,28 @@ 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.54.0）              ← 只读检查 + 报告，不执行 iterate
+```
+
+（各步详细说明见下方对应节标题的 ①–⑤ 编号。）
 
-**架构快照门禁（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`。
+> **本块是全流程中该顺序的【唯一真相源】**（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`。
 
-### Architecture Merge (v0.10 §28-§31) — MUST run first
+**架构快照门禁（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`（引用，非调用）。
 
-Merge change-level architecture artifacts to the global `docs/architecture/` baseline **before** any other post-verification step:
+### ① Architecture Merge (v0.10 §28-§31) — MUST run first
+
+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 +178,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（无架构增量可回写），用显式跳过键登记：
 
-### Prototype Sync (v0.5)
+```bash
+tf state set <change-dir> arch_merge_skipped true
+tf state set <change-dir> arch_merge_skip_reason "<理由>"
+```
 
-After `arch-merge` completes, run prototype-sync to merge UX deltas back to the global prototype:
+### ② State Transition
+
+Run `tf state transition <change-dir> closing`. If delta specs exist, route to `spec-merger`.
+
+**顺序（MUST）**：见 `### ⚠ 执行顺序` 的 ①–⑤（**本步是 ②**，前置 ① 已完成）。不得并行——全局文档不得处于半更新态。
+
+### ③ Prototype Sync (v0.5)
+
+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 +223,31 @@ 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.
+读取 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，单一来源）。
 
-### Compound Capture Check (v0.5；v0.49.0 §83.3.5 明确写入方)
+**Compound Capture Check（v0.5）**：closing 前自检本 change 是否产生了可沉淀的经验（强制回退 / 复发根因 / 范围外扩 / 契约漂移）；有则写入 change 根的 `learnings.md`，每条 `## <title>` 带 frontmatter（`phase`/`domain`/`type`/`severity`/`date`）。该文件正是 `compound-captured` guard 检查、`tf solutions promote` 读取的对象。
 
-Before finalizing the closing, check if this change produced any learnable moments:
+> **本节的展开版（条目质量要求、`tf solutions capture` 与 `learnings.md` 的分工、Prototype Sync / Worktree Deisolation / Code Landing 全流程）见 `references/closing-procedures.md`**——该处为超集，本节不再重复（v0.53.0 §115.10：同名节曾两处各自维护，属根因 Ⅲ 的同一类漂移）。
 
-- 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?
+### ⑥ 设计系统待办检查（v0.54.0）— 只读检查 + 报告
 
-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).
+检查 `.team-flow/design-system/pending.md` 非空时，在 closing summary 的 `design_system_pending` 中报告条目数并标注 `needs user confirmation`（报告触发条件与细节见 `references/closing-procedures.md`）。
 
-`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`。
+**只读，不执行 iterate**（由 design-system skill 在用户确认后触发）；**单写者约束**：写入/移除一律由 design-system skill 执行。快速 closing 时 pending.md 保留不动。
 
 ### 阶段产物同步门禁点（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 +283,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 正文句）`），本次改动插入段落使其失效。**行号引用在密集改动期必然漂移，已改为按标题引用**——同轮 `team-flow-workspace/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
@@ -86,3 +96,13 @@ If an `e2e/` suite exists for the change:
 ## Lightweight Closure (hotfix/tweak)
 
 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.54.0）
+
+`Post-Verification` 顺序的 ⑥（只读检查 + 报告，不执行 iterate）。检查 `.team-flow/design-system/pending.md`（原型阶段"暂不处理"的设计系统增量暂存）：
+
+1. **非空时**：读取未处理条目（格式 `{描述} | 来源: <change-id 或 s2-prototype> | 时间: <ISO>`），在 closing summary 的 `design_system_pending` 字段列出并标注 `needs user confirmation`
+   - **报告触发条件（防仪式膨胀）**：仅当「本 change 产生过 `ds_increment`（来源标注含本 change-id）」**或**「pending.md 非空且本次会话未询问过」时显式列出并建议确认；其余情况仅记录条目数
+2. **不执行 iterate**——iterate 由 design-system skill 在用户确认后另行触发；主代理提示二选一：closing 等待执行 / 保留 pending 待下次绘制处理
+3. **快速 closing（无交互路径）**：pending.md **保留不动**（不丢失，下次生效）
+4. **单写者约束**：本步**只读**——写入/移除一律由 design-system skill 的 iterate 流程执行（避免多 change 并发读改写导致丢失更新）

package/skills/workflow-bootstrap/SKILL.md

@@ -12,7 +12,7 @@ description: 既有项目接入初始化器。在首次使用 team-flow 时执
 ```
 workflow-bootstrap（一次性，手动触发）
   → B1 代码库侦察 → B1.5 conventions → B2 架构基线 → B3 领域词汇 → B4 目录初始化
-  → B4.5 CLAUDE.md 初始化 → B5 路径判断
+  → B4.5 CLAUDE.md 初始化 → B4.6 Design System 起点选择 → B5 路径判断
   → 进入 workflow-orchestrator S1（注入 baseline 上下文）
 ```
 
@@ -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 完整**：
@@ -209,6 +218,18 @@ Step 2: 确定性提取（兜底）
 
 **不做的事**：不写 SOP 流程（由 skill 负责）、不写变更级状态机（由 workflow skill 负责）、不列可自动发现的文件清单。
 
+### B4.6: Design System 起点选择（advisory，v0.54.0 新增）
+
+> 编号说明：B4.5 已被占用（CLAUDE.md 初始化），本步骤为 B4.6。
+
+`.team-flow/design-system/` 不存在时，AskUserQuestion 呈现起点四选一（**不阻断**，延续 advisory 约定）：
+
+> 「检测到项目尚无设计系统。选择起点方式：[从模板库选择 | 逆向建库 | 从零创建 | 跳过]」
+
+- **模板库**：调 `/team-flow:design-system`（起点=模板库）——由该 skill 呈现 `${CLAUDE_PLUGIN_ROOT}/templates/design-systems/registry.json`（8 个参考设计系统），选定后执行导入并**续跑 Step 5 评审 → Step 6 落盘**（含 primer 生成 + guard 校验）。**本步骤不直接调转换器**：转换器只产 base.md，缺少 primer 会让后续 prototype Step 0 对 `contract: v1` 系统直接 blocked（v0.54.0 P4 实证死路）
+- **逆向建库 / 从零创建**：调 `/team-flow:design-system`（create-from-code / 交互式 6 步）
+- **跳过** → 继续 B5；**已存在** → 跳过
+
 ### B5: Path Decision（路径判断，v0.42.0 重构：降级路径设计）
 
 询问用户。**分组展示**——用户先决定"要不要把地基打牢"（第一组），再决定"打完地基做什么"（第二组）：
@@ -249,7 +270,7 @@ Step 2: 确定性提取（兜底）
 ## Output Standard
 
 每次交互结束时说明：
-1. 已完成的阶段（B1-B1.5-B2-B3-B4-B4.5-B5）
+1. 已完成的阶段（B1-B1.5-B2-B3-B4-B4.5-B4.6-B5）
 2. 已产出的制品（baseline.md / conventions / ARCHITECTURE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md / CONCEPTS.md / CLAUDE.md / cross-check-report.md（如执行 B）/ 目录结构）
 3. 下一步建议（调用哪个 skill）
 

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 新增）