@xulthekl/team-flow 0.59.0 → 0.61.0

package/docs/{usage-guide.md → team-flow /344/275/277/347/224/250/350/257/264/346/230/216/357/274/210/347/240/224/345/217/221/345/233/242/351/230/237/347/211/210/357/274/211.md" }

@@ -1,6 +1,6 @@
 # team-flow 使用说明（研发团队版）
 
-> 版本锚点：v0.59.0（28 skills + 17 agents）· 更新日期：2026-09-12
+> 版本锚点：v0.61.0（28 skills + 17 agents）· 更新日期：2026-09-21
 > 读者：使用 team-flow 做日常研发的工程师。不需要你懂插件内部实现，只需要照着路径走。
 > 配套文档：安装细节见 [INSTALL.md](../INSTALL.md)；状态机细节见 [state-machine.md](state-machine.md)；决策点细节见 [decision-points.md](decision-points.md)；平台差异见 [platform-matrix.md](platform-matrix.md)。
 
@@ -42,7 +42,7 @@
 
 ```
 产品级（workflow-orchestrator）——管"做什么、什么顺序"
-  模糊需求 → PRD+原型 → 实施计划 → 产品级架构 → change 拆分分发 → 全局监控
+  模糊需求 → PRD+原型 → 产品级架构（ARCH）→ 实施计划 → change 拆分分发 → 全局监控
                               │
                               ▼ 每个 change 独立走一遍
 变更级（workflow-start）——管"怎么做"，8 态状态机
@@ -65,13 +65,15 @@
 npm install -g @xulthekl/team-flow
 ```
 
-> SessionStart hook 会在每次会话启动时自动核对 tf CLI 版本与插件版本，不一致会自动 `npm install -g` 同步，**通常你不需要手动升级 CLI**。
+> SessionStart hook 会在每次会话启动时自动核对 tf CLI 版本与插件版本，**只升不降**（CLI 比插件新时跳过同步——避免旧版插件缓存把新 CLI 降级），低于插件版本时自动 `npm install -g` 同步，**通常你不需要手动升级 CLI**。
 
 ### 2.2 验证安装
 
 ```bash
-tf --version        # 应输出 0.44.0
-tf doctor           # 体检：版本一致性、hooks、runtime skills、docs 完整性
+tf --version        # 应输出 0.60.0
+tf doctor           # 体检 13 项固定 + 1 项条件：版本一致性 / plugin author / hooks / Codex manifest / skills /
+                    # runtime 分发 / dist / Node 版本 / docs / change 状态 / change 测试门禁 / 架构状态 / 复利台账
+                    # （末项"配置"仅在仓库根存在 team-flow.config.json 时出现）
 ```
 
 在 Claude Code 会话中，新开一个会话应能看到注入的 team-flow 上下文提示。输入 `/team-flow:` 应能补全出 `workflow-start`、`workflow-orchestrator` 等 skill。
@@ -83,8 +85,8 @@ tf doctor           # 体检：版本一致性、hooks、runtime skills、docs
 | 等级 | 平台 | 门禁能力 |
 |------|------|---------|
 | ★ 完整 | Claude Code | PreToolUse 硬拦截（非 build 态禁止写实施代码）+ 状态机门禁 + 规则注入 |
-| ☆ 中等 | Cursor | SessionStart 注入 + phase-guard 规则文件（软约束，无硬拦截） |
-| ○ 提示级 | Codex / Gemini CLI / OpenCode / Cline / Kiro / Windsurf 等 | phase-guard 规则文件常驻上下文 + CLI 门禁；依赖模型自觉 |
+| ☆ 中等 | Cursor / GitHub Copilot CLI | SessionStart 注入 + phase-guard 规则文件（软约束，无硬拦截） |
+| ○ 提示级 | Codex / Gemini CLI / OpenCode / WorkBuddy / ZCODE / Trae / Cline / Kiro / Windsurf 等 | phase-guard 规则文件常驻上下文 + CLI 门禁；依赖模型自觉 |
 
 **含义**：在非 Claude Code 平台上，状态机门禁（`tf state transition` 时的 guard 校验）依然硬生效，但"非 build 态写代码"没有运行时硬拦截——靠规则文件提示约束。
 
@@ -97,6 +99,9 @@ tf doctor           # 体检：版本一致性、hooks、runtime skills、docs
 ```
 你手头是什么任务？
 │
+├─ 工作空间还没有代码服务（空目录 / 无技术栈特征）
+│     → /team-flow:project-initialize（服务初始化引导，见 5.1）
+│
 ├─ 既有项目第一次用 team-flow（还没有 docs/architecture/baseline.md）
 │     → 先跑一次 workflow-bootstrap（一次性接入，见 5.1）
 │
@@ -106,20 +111,27 @@ tf doctor           # 体检：版本一致性、hooks、runtime skills、docs
 ├─ 已在一个 change 目录里（有 .team-flow.yaml），要继续 / 开始 / 恢复
 │     → /team-flow:workflow-start（变更级唯一入口，见 5.3）
 │
-├─ 紧急小 bug 修复（≤2 任务、≤2 文件、不动 schema/API）
+├─ 紧急小 bug 修复（≤2 任务、≤2 文件，不动 schema/API、不新增模块）
 │     → hotfix 模式（workflow-start 会自动识别，见 5.4）
 │
-├─ 极小调整（≤4 任务的纯配置/文案类）
+├─ 极小调整（≤4 任务、纯配置/文档类文件，不动 schema/API、不新增模块）
 │     → tweak 模式（workflow-start 自动识别，见 5.4）
 │
 └─ 独立的工具性操作
       ├─ 纯架构设计（不走工作流）→ /team-flow:architecture-design
       ├─ 原型绘制/迭代 → /team-flow:prototype
-      ├─ 设计系统创建 → /team-flow:design-system
+      ├─ 设计系统创建/迭代 → /team-flow:design-system
+      ├─ 业务场景/流程分析 → /team-flow:business-analysis
       ├─ 想法探索（不产 PRD）→ /team-flow:ce-ideate
       ├─ 聚焦头脑风暴（已有明确主题，不要全流程）→ /team-flow:ce-brainstorm
+      ├─ 已有冻结 PRD，只做实施计划 → /team-flow:ce-plan
+      ├─ 产品战略锚点 STRATEGY.md → /team-flow:ce-strategy
+      ├─ 把 markdown 发布到 Proof 共享 → /team-flow:ce-proof
       ├─ E2E 测试生成/执行 → /team-flow:e2e
-      └─ 沉淀一条经验 → /team-flow:ce-compound
+      ├─ 长对话上下文交接 → /team-flow:session-handoff
+      ├─ 沉淀一条经验 → /team-flow:ce-compound
+      ├─ 夜间/离席期间代做决策（可选启用）→ /team-flow:jarvis
+      └─ 反馈工作流本身的问题 → /team-flow:workflow-feedback
 ```
 
 **三条反模式，不要做**：
@@ -150,21 +162,25 @@ exploring ──→ specifying ──→ bridging ──→ approved-for-build
 - tweak：`exploring → approved-for-build`（跳过探索/规划/契约）
 
 **规则**：
-- 所有状态转换必须走 `tf state transition`，它内部自动执行 guard 门禁校验，任一维度 FAIL 就不落盘。**不要手工编辑 `.team-flow.yaml` 的 state 字段**——这是红线，CLI 会拒绝非法写入，hook 也永远拦截对该文件的手工修改。
-- 回退是合法的：executing 可以退回 specifying/bridging（发现需求变了，回去改规划，而不是硬改代码）。
+- 所有状态转换必须走 `tf state transition`，它内部自动执行 guard 门禁校验，任一维度 FAIL 就不落盘。**不要手工编辑 `.team-flow.yaml` 的 state 字段**——这是红线：`state` 不在 `tf state set` 白名单（CLI 直接拒绝），且非 build 态下对该文件的 Write/Edit 会被 hook 拦截（build 三态的放行是留给子代理回写产物的，不是留给改状态的）。
+- 回退是合法的（共 7 条路径）：`specifying→exploring`、`bridging→specifying`、`approved-for-build→specifying|bridging`、`executing→specifying|bridging`、`closing→specifying`。发现需求变了就回去改规划，而不是硬改代码。
 - `closing` 即收尾完成态；`abandoned` 是终态，不能再转出。
 
 ### 4.2 三种 workflow 模式
 
-workflow-start 在初始化时自动推断（`tf runtime infer`），你也可以在 DP-0 确认时调整：
+workflow-start 在初始化时自动推断（`tf runtime infer`），你也可以在 DP-0 确认时调整。**推断只在 `workflow` 为 `auto`/未设置时发生**——一旦显式定成 full/hotfix/tweak，后续直接沿用，不再重新推断：
 
-| 模式 | 判据（自动推断） | 特点 | 豁免项 |
+| 模式 | 判据（自动推断） | 特点 | 门禁差异（对比 full） |
 |------|----------------|------|--------|
-| **full** | 默认（不满足下面两个） | 全流程：需求探索→架构门→四件套→契约→执行计划→TDD→逐 wave 审查→完整收尾 | 无 |
-| **hotfix** | ≤2 任务、≤2 文件、不动 schema/API | 跳过需求探索和规划制品，最小契约仍需 DP-3 批准 | test-matrix-complete、执行计划回执 |
-| **tweak** | ≤4 任务的纯配置/文档类 | 直接进 approved-for-build，直接编辑 | 执行计划、逐 wave 审查回执、测试矩阵 |
+| **full** | 默认（不满足下面两个） | 全流程：需求探索→架构门→四件套→契约→执行计划→TDD→逐 wave 审查→完整收尾 | 基准：`executing→closing` 挂 10 维 |
+| **hotfix** | ≤2 任务、≤2 文件，且不动 schema/API、不新增模块 | 跳过需求探索和规划制品，最小契约仍需 DP-3 批准 | 入口换一套更轻的维度：`contract-current`+`dp3-approved` 取代 full 的 artifacts-exist / schema-valid / contract-fresh / dp-gate-passed；不查 `test-matrix-ready`。出口 6 维——省 `test-matrix-complete`、`arch-snapshot`、`delegation-status`、`arch-merged`，**但执行计划与逐 wave 审查回执仍要** |
+| **tweak** | ≤4 任务，且文件全是配置/文档类（无代码文件）、不动 schema/API、不新增模块 | 直接进 approved-for-build，直接编辑 | 入口不查 `execution-plan-ready` / `test-matrix-ready`，但仍查 `artifacts-exist`+`contract-fresh`+`dp-gate-passed`。出口仅 3 维（`tasks-complete`、`tests-passing`、`specs-merged`），省掉其余 7 项 |
+
+**注意三件事**：
 
-**注意**：hotfix/tweak 豁免测试矩阵与 `tasks.md` 时**必须显式 skip 并写明理由**（`tf state set test_matrix_skipped true` + `test_matrix_skip_reason`；`tf state set tasks_skipped true` + `tasks_skip_reason`），门禁不接受无理由跳过。架构设计判断门（五项检查）**两种模式都不豁免**。
+1. hotfix/tweak 豁免测试矩阵与 `tasks.md` 时**必须显式 skip 并写明理由**（`tf state set <dir> test_matrix_skipped true` + `test_matrix_skip_reason`；`tf state set <dir> tasks_skipped true` + `tasks_skip_reason`），门禁不接受无理由跳过。
+2. **架构设计判断门（五项检查）两种模式都不豁免**，tweak/hotfix 同样要过 architecture-design 子代理（通常结论是 skip）。
+3. **tweak 仍要完成一次 DP-4**：它的 `approved-for-build→executing` 挂着 `dp-gate-passed`，该维度要求 `dp_4_result` 非空，而这个字段只能由 `tf execution plan --confirm` 写入（前置是 `tf execution recommend`）。轻的是**逐 wave 审查**，不是决策点本身。
 
 ### 4.3 决策点（DP）——什么时候需要你拍板
 
@@ -176,13 +192,18 @@ workflow-start 在初始化时自动推断（`tf runtime infer`），你也可
 | DP-1 | 需求探索结束 | scope / non-goals / 成功标准 |
 | DP-A | 架构设计产出后 | 架构三件套是否接受（可选调整，调整回原子代理修改） |
 | DP-2 | 四件规划制品完成 | proposal/specs/design/tasks 评审批准 |
-| DP-3 | 执行契约生成后 | **硬门禁**：契约批准。没有你的批准记录，任何实施都不被允许 |
-| DP-4 | 执行模式选择 | `tf execution recommend` 展示证据后，你选 SDD/Inline/Batch Inline |
+| DP-3 | 执行契约生成后 | **硬门禁**：契约批准。取值须以 `approved` 开头，否则 `bridging→approved-for-build` 转换被拒 |
+| DP-4 | 执行模式选择 | `tf execution recommend` 展示证据后，你选 `inline` / `batch-inline` / `sdd` / `glaf4-delegation` 四种之一 |
 | DP-5 | 调试受阻 | 3+ 次修复失败 → 升级为架构问题的判断确认 |
 | DP-6 | 收尾验证 | 验证结论 pass/conditional/fail |
 | DP-7 | 归档 | 确认归档（系统会核验 DP-0~DP-6 全部齐备） |
 
-产品级编排还有 G1-G5 五个团队同步点（`tf publish` 推送阶段产物），每次都会问你：推送 / 仅提交 / 暂不同步。
+**除了 DP，还有两类阻塞确认点**：
+
+- **Step 5c Code Landing**（收尾验证内，早于 DP-6）：worktree 代码是否合并回主分支——A 现在合并 / B 暂不合并 / C 无需合并。
+- **G1-G5 团队同步点**（`tf publish` 推送阶段产物）：每次问你 推送 / 仅提交 / 暂不同步。G1（PRD）/ G2（ARCH）/ G3（S4 拆分）在产品级编排；**G4 在变更级 workflow-start（DP-3 之后）**，**G5 在 release-archivist 收尾**。
+
+**确认点可以合并**（v0.50.0 起，减少交互轮次而非门禁强度）：DP-0 + DP-A、DP-3 + G4 + DP-4、DP-7 + Code Landing + G5 三组，在条件满足时可各合并成一次 AskUserQuestion；合并后 `dp_0_confirmed` / `dp_a_result` / `dp_3_result` / `dp_4_result` 等字段仍照常落盘。
 
 ### 4.4 核心产物清单
 
@@ -211,56 +232,91 @@ workflow-start 在初始化时自动推断（`tf runtime infer`），你也可
 tf runtime guard check <change-dir> <from-state> <to-state> [--workflow full|hotfix|tweak]
 ```
 
-关键门禁与应对（完整清单见 [9. FAQ](#9-faq-与排障)）：
+**full 模式的完整转换矩阵**（19 个维度 + 1 个 workflow 限制维度）：
+
+| 转换 | 维度 |
+|------|------|
+| exploring→specifying | arch-design、arch-readiness |
+| specifying→bridging | artifacts-exist、schema-valid |
+| bridging→approved-for-build | artifacts-exist、schema-valid、contract-fresh、dp-gate-passed、dp3-approved |
+| approved-for-build→executing | artifacts-exist、contract-fresh、dp-gate-passed、execution-plan-ready、test-matrix-ready |
+| **executing→closing** | **10 维**：tasks-complete、tests-passing、specs-merged、execution-plan-ready、execution-reviews-passed、compound-captured、test-matrix-complete、arch-snapshot、delegation-status、arch-merged |
+| executing↔debugging | debugging 入口无门禁；回 executing 挂 contract-fresh、execution-plan-ready |
+| exploring→bridging / exploring→approved-for-build | 0 维，但**一一对应**：`exploring→bridging` 仅 hotfix 可走、`exploring→approved-for-build` 仅 tweak 可走；full 走或其他组合都直接 FAIL |
+| 7 条回退 + 6 条放弃 | 0 维（回退是合法操作，不需要门禁放行） |
+
+高频阻断与应对：
 
 | 门禁 | 拦在哪 | 常见原因与出路 |
 |------|--------|---------------|
-| contract-fresh | bridging→approved-for-build 等 | 规划制品改了没重建契约 → 回 contract-builder 重生成 |
-| dp-gate-passed | approved-for-build→executing | DP-3/DP-4 没记录 → 完成对应决策 |
-| test-matrix-ready | approved-for-build→executing | 契约缺 Test Matrix 段或 test-matrix.md 为空 → 回 bridging 生成，或显式 skip+理由 |
-| tests-passing | executing→closing | 只认 `tf test record` 的程序化证据 → 跑测试并记录 |
-| execution-reviews-passed | executing→closing | 有 wave 缺 pass 审查回执 → 补审查 |
-| compound-captured | executing→closing | 缺 learnings.md → `tf solutions capture` 或显式 skip |
+| contract-fresh / contract-current | bridging→approved-for-build 等 | 规划制品改了没重建契约 → 回 contract-builder 重生成，或 `tf state rebuild` 后重生成 |
+| dp-gate-passed | bridging→approved（要 dp_3）/ approved→executing（要 dp_4） | DP-3/DP-4 没记录 → 完成对应决策 |
+| dp3-approved | bridging→approved-for-build | `dp_3_result` 不以 `approved` 开头（HOLD、pending 等值都会被拒） |
+| execution-plan-ready | approved→executing、executing→closing | 执行计划缺失或 hash/revision 与当前不一致 → 重跑 `tf execution recommend` + `plan --confirm` |
+| test-matrix-ready / complete | approved→executing / executing→closing | 契约缺 Test Matrix 段或 test-matrix.md 为空 → 回 bridging 生成，或显式 skip+理由 |
+| tasks-complete | executing→closing | tasks.md 有未勾选项 → 回写勾选；hotfix/tweak 可显式 skip+理由（full 不允许） |
+| tests-passing | executing→closing | 只认 `tf test record` 的程序化证据（`recorded-by=tf-test-record` + 证据文件存在 + `failed=0` + `total>0`） |
+| specs-merged | executing→closing | 有 delta specs 但没合并 → 跑 `tf sync <change-dir>`（无 delta 即天然放行） |
+| execution-reviews-passed | executing→closing | 有 wave 缺 pass 审查回执 → 补审查（回执 base≠head 且 base 是 head 祖先） |
+| compound-captured | executing→closing | 缺 `learnings.md`（change 根目录，非空）→ 写它，或 `tf state set <dir> compound_skipped true` |
 | 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` |
+| delegation-status | executing→closing | 非 glaf4-delegation 模式直接 PASS；该模式须 `delegation_status=success` |
+| artifacts-exist / schema-valid | specifying→bridging 起 | 四件套缺失或 Validator 不通过（SHALL/MUST、Scenario、跨段冲突） |
 
-**设计哲学**：门禁硬，但每条都有逃生舱——存量豁免（字段缺失即视为老 change）、显式 skip+理由、`--force`/`--acknowledge-*` 参数。豁免一律留痕，可审计。
+**设计哲学**：门禁硬，但**可豁免的维度都有留痕出口，不可豁免的维度只能改产物**——这点要分清，不要以为万事都能绕：
+
+- **可豁免**（显式登记，可审计）：`schema_version` 缺失（= 存量 change）、`arch_baseline` 缺失（= 存量项目，WARN 放行）、`test_matrix_skipped`+理由、`tasks_skipped`+理由（**仅 hotfix/tweak**）、`compound_skipped`、`arch_merge_skipped`+理由、`arch_design_decision=skipped`、`iterations/vN/SKIPPED` 物化。
+- **不可豁免**（判据不满足即 FAIL，无 skip 键）：`dp3-approved`、`dp-gate-passed`、`artifacts-exist`、`schema-valid`、`contract-fresh`/`contract-current`、`execution-plan-ready`、`execution-reviews-passed`、`delegation-status`。这些只能靠补产物/补决策通过。
+- `--force` 与 `--acknowledge-recommendation` **不是 guard 门禁的逃生舱**——前者属 `tf isolate` / `tf deisolate --merge`，后者属 `tf execution plan`（选了非推荐模式时的确认）。
 
 ### 4.6 复利闭环——change 关闭时自动发生什么
 
 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/）
-  → tf deisolate --merge（worktree 代码合并回主分支，Step 5c Code Landing）
+① 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/）
+⑥ 设计系统待办检查（只读 .team-flow/design-system/pending.md，写进 closing summary）
 ```
 
+> **代码合并不在这条链上**：`tf deisolate --merge` 属收尾验证的 **Step 5c Code Landing**——在回写链**之前**执行，且是阻塞确认点（现在合并 / 暂不合并 / 无需合并）。
+
 这就是"改动不烂尾、知识不流失"的机制保障。经验沉淀后，下一个 change 的对应阶段会通过 `tf solutions inject` 自动注入相关经验（默认 top-5；调用点须显式传 `--limit`，否则 cross-phase 条目满载时本阶段新增条目永不可达）。
 
 ---
 
 ## 5. 场景实战
 
-### 5.1 场景一：既有项目首次接入（一次性）
+### 5.1 场景一：项目首次接入（一次性）
+
+**适用**：项目已有代码，第一次用 team-flow。
 
-**适用**：项目已有代码，第一次用 team-flow。全新空项目跳过本节直接看 5.2。
+**如果工作空间还是空的**（没有代码服务、没有技术栈特征），先走服务初始化：
+```
+在 Claude Code 中：
+> /team-flow:project-initialize
+```
+它会引导你选架构形态（glaf4 体系 / 前端分离 / 单体微服务 / 拆分）、确认服务命名、创建服务子目录，再委托对应的初始化骨架（glaf4 走 glaf4-dev 的 PROJECT_INITIALIZE，非 glaf4 则回到下面的 bootstrap 全新项目路径）。
 
+**已有代码库**则直接接入：
 ```
 在 Claude Code 中：
 > /team-flow:workflow-bootstrap
 ```
 
-流程（B1→B5）：
-1. **B1 代码侦察**：确定性脚本 + 并行子代理分析代码库，产出 `docs/architecture/baseline.md`（核心基线）
-2. **B1.5 conventions 生成**：按技术栈（java/js/python）生成项目规范到 `.team-flow/conventions/`
-3. **B2 架构基线文档化**：ARCHITECTURE.md / DATABASE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md（≥5 模块或 ≥10 文件才执行；优先导入你已有的 DDL/物理模型/Swagger 成果物）
+流程（B1 → B1.5 → B2 → B3 → B4 → B4.5 → B4.6 → B5）：
+1. **B1 代码侦察**：确定性脚本 + 并行子代理分析代码库，产出 `docs/architecture/baseline.md`（**As-Is 叙述的唯一载体**）
+2. **B1.5 conventions 生成**：按技术栈（java/js/python）生成项目规范到 `.team-flow/conventions/`；全新项目在此做交互式技术栈选择 + 可选骨架生成
+3. **B2 架构基线文档化**（≥5 模块或 ≥10 文件才执行）：经 `tf arch scaffold` 建全局台账空骨架，再把你的成果物并入——**DDL 进 `schema-baseline.sql`，物理模型和 Swagger 端点清单并入 `baseline.md`**。注意 `DATABASE.md` / `PHYSICAL-MODEL.md` / `API-INDEX.md` / `INDEX.md` 四个文件是 `tf arch-merge` 无条件重建的**生成式制品，B2 不写它们**（手写的会在首次 merge 时被整体覆盖，知识就丢了）
 4. **B3 领域词汇提取**：从代码命名提取术语到 `docs/architecture/CONCEPTS.md`
-5. **B4 目录初始化**：requirement/ 、prototype/ 、docs/ 、changes/
-6. **B5 路径判断**：问你接下来去哪（进 orchestrator / 头脑风暴 / 仅建基线等）
+5. **B4 目录初始化**：`requirement/ prototype/ docs/architecture/ docs/solutions/ changes/`
+6. **B4.5 项目 CLAUDE.md 初始化**：生成/更新项目级开发约定
+7. **B4.6 设计系统起点选择**（advisory，不阻断）：检测到项目没有设计系统时，问你六选一（模板库导入 / 逆向建库 / 从零创建 / 移植同类 / 通用起点 / 从规范文档导入）或跳过
+8. **B5 路径判断**：分两组问你——**地基组**（A 逆向重建完整架构 / B 交叉验证 bootstrap 产物 / C 真实性核对）与**进流程组**（D 具体功能需求 → orchestrator / E 模糊产品方向 → ce-brainstorm / F 仅建基线）
 
 **你要做的**：回答它的问题；有现成的架构文档/DDL/Swagger 就喂给它（比 AI 推断准确得多）。
 
@@ -274,16 +330,19 @@ tf arch-merge（架构增量 → docs/architecture/ 全局当前态）
 > 我想给订单系统加一个批量导出功能，支持异步任务和邮件通知
 ```
 
-编排器会带你走 S1→S5（每步都会等你确认）：
+编排器会带你走 S1 → S2 → ARCH → S3 → S4 → S5（每步都会等你确认）：
 
 | 阶段 | 发生什么 | 你要做什么 |
 |------|---------|-----------|
-| S1 路径路由 | 读 registry.yaml，判断入口路径（全新/续版/重新计划…），注入基线+复利经验 | 确认路由（路由是建议，你可以改） |
-| S2 PRD+原型 | ce-brainstorm 产出 `requirement/vN/prd.md` 草稿 → PRD 完整性自动评审 → 原型循环（产出→自动评审≤3轮） | 回答澄清问题；审 PRD；审原型（美观/体验只有你能判）；确认后冻结 |
-| S3 计划 | ce-plan 产出 `requirement/vN/plan.md`：change 拆分 + 依赖 DAG + 技术方向 | 审计划；发现 PRD 问题会回退 S2 |
-| ARCH 产品级架构 | architecture-design product 模式 8 步设计，产出 `docs/architecture/iterations/vN/architecture.md` 快照，自动评审 PASS 才放行 | 审架构（skip 也要物化 SKIPPED 标记） |
+| S1 路径路由 | 读 registry.yaml，判断入口路径（全新/续版/重新计划…），确认项目模式（single/monorepo/multi-repo，写 `repo_layout`），注入基线 + 复利经验 | 确认路由与项目模式（路由是建议，你可以改） |
+| S2 PRD+原型 | ce-brainstorm 产出 `requirement/vN/prd.md` 草稿 → PRD 完整性自动评审（含 §8.4 契约级细节维度）→ 原型循环（产出→自动评审≤3轮） | 回答澄清问题；审 PRD；审原型（美观/体验只有你能判）；确认后冻结 |
+| **ARCH 产品级架构** | architecture-design product 模式 8 步设计，产出 `docs/architecture/iterations/vN/architecture.md` 快照，产品级评审门 PASS 才放行 | 审架构（skip 也要物化 SKIPPED 标记） |
+| **Pre-check 服务初始化检测** | 从架构快照的注册表提取本次涉及的服务，检查服务子目录与技术栈特征是否就绪 | 缺服务 → 按引导跑 project-initialize；已存在但没拉取 → git pull |
+| S3 计划 | ce-plan 产出 `requirement/vN/plan.md`：change 拆分 + 依赖 DAG + 技术方向（**基于 ARCH 定稿**） | 审计划；发现 PRD 问题会回退 S2 |
 | S4 拆分分发 | change-split-auditor 审计拆分质量（PASS 硬前置）→ 创建 `changes/v{N}-C{n}-{name}/` 脚手架 + change-brief.md | 确认拆分结果 |
-| S5 监控 | 多 change 并行时跟踪进度、跨 change 冲突检测 | 按提示进入各 change 执行 |
+| S5 监控 | 多 change 并行时跟踪进度、跨 change 冲突检测（**change ≥ 2 时必选**） | 按提示进入各 change 执行 |
+
+> **ARCH 排在 S3 之前**（2026-08-19 起的顺序）：S3 的计划与 S4 的拆分是**最终任务拆分**，必须基于架构定稿——先有架构再拆任务，避免拆完发现架构支撑不了。
 
 **然后**：对每个 change 进目录走 5.3（执行顺序按 DAG，如 C1 →（C2∥C3）→ C4）。
 
@@ -306,14 +365,21 @@ workflow-start 会自动：
 
 ```
 需求模糊？ → need-explorer 交互式澄清（DP-1）
-  → architecture-design 五项检查（涉及架构变更才做三件套，否则 skip；自动审查+DP-A）
+  → architecture-design 五项检查（涉及架构变更才做三件套，否则 skip；自动审查 + DP-A）
   → spec-writer 产出四件套（proposal/specs/design/tasks，逐个确认后 DP-2）
-  → contract-builder 产出契约+测试矩阵（DP-3 批准，硬门禁）
-  → tf execution recommend → 你选执行模式 → tf execution plan --confirm（DP-4）
+  → contract-builder 产出契约 + 测试矩阵
+  → Pre-check 服务缺漏检测（workflow-start 路由前触发；缺服务 → 引导 project-initialize）
+  → DP-3 批准契约（硬门禁）+ G4 团队同步 + DP-4 执行模式（三点可合并为一次确认）
+  → tf execution recommend → tf execution plan --confirm
+       （四选一：inline / batch-inline / sdd / glaf4-delegation）
   → tf isolate（worktree 隔离，保护 main）
   → build-executor 逐 wave TDD 实施（RED→GREEN→REFACTOR）
   → 每个 wave 完成 → code-reviewer 审查 → findings 修复 → re-review
-  → 全部 wave pass → release-archivist 收尾验证（DP-6/DP-7）→ 回写链 → closing
+  → 全部 wave pass → release-archivist 收尾验证：
+       ├─ Step 5b E2E 验证（矩阵含 E2E 用例时触发）
+       ├─ Step 5c Code Landing（阻塞确认：合并 / 暂不合并 / 无需合并）
+       └─ DP-6 验证结论 → DP-7 归档（DP-7 + Code Landing + G5 可合并）
+  → 回写链（arch-merge → transition → prototype-sync → test-merge → promote → DS 待办检查）→ closing
 ```
 
 **关键纪律**（工作流会引导，你知道原理更好配合）：
@@ -324,20 +390,28 @@ workflow-start 会自动：
 
 ### 5.4 场景四：hotfix 与 tweak（快速路径）
 
-**hotfix**（紧急 bug，≤2 任务 ≤2 文件不动 schema/API）：
+**hotfix**（紧急 bug：≤2 任务 ≤2 文件，不动 schema/API、不新增模块）：
+
 ```
 workflow-start 自动识别为 hotfix
-→ exploring 直接跳 bridging（跳过需求探索和四件套）
-→ 最小契约仍要 DP-3 批准 → 实施 → tests-passing 仍要程序化证据 → closing
+→ exploring 直接跳 bridging（跳过需求探索；proposal.md / design.md / specs/ 可省）
+→ 最小契约仍要 DP-3 批准（bridge→approved-for-build 挂 contract-current + dp3-approved）
+→ 进 executing 仍要 execution-plan-ready（即 DP-4 的执行计划）
+→ 实施 → closing 仍考 6 维：tasks-complete、tests-passing、specs-merged、
+   execution-plan-ready、execution-reviews-passed、compound-captured
 ```
 
-**tweak**（纯配置/文案小调整，≤4 任务）：
+**tweak**（≤4 任务、纯配置/文档类文件，不动 schema/API、不新增模块）：
+
 ```
 workflow-start 自动识别为 tweak
-→ exploring 直接跳 approved-for-build → 直接编辑 → 收尾（豁免执行计划与逐 wave 审查）
+→ exploring 一步跳到 approved-for-build（0 维门禁，比 hotfix 还快）
+→ 直接编辑 → closing 只考 3 维：tasks-complete、tests-passing、specs-merged
 ```
 
-两者都：**架构五项检查不豁免**（通常结果是 skip，但检查会跑）；测试矩阵豁免必须显式 skip+理由。
+> **tweak 的"轻"在出口，不在入口**（实测）：它的 `approved-for-build→executing` 挂着 `artifacts-exist` + `contract-fresh` + `dp-gate-passed` 三项——即使编排层不派 spec-writer / contract-builder，转换时**仍要求** proposal/design/tasks/specs 与 `execution-contract.md` 存在且 hash 一致，并完成一次 DP-4。从零新建的 tweak change 会卡在这一步。
+
+两者共同点：**架构五项检查不豁免**（通常结论是 skip，但检查会跑）；测试矩阵/tasks.md 豁免必须显式 skip + 理由（`tasks_skipped` 在 full 模式下会被直接拒绝）。
 
 ### 5.5 场景五：会话中断了怎么办
 
@@ -365,8 +439,9 @@ cd changes/<name>
 | 改了规划制品后刷新 hash | `tf state rebuild <change-dir>` |
 | 转换状态 | `tf state transition <change-dir> <to-state>`（门禁自动执行） |
 | 预检门禁 | `tf runtime guard check <change-dir> <from> <to>` |
-| 记录测试结果（closing 必需） | `tf test record <change-dir> --from <runner输出文件>`（支持 maven-surefire/jest/pytest，可 auto 识别） |
-| 隔离工作区 | `tf isolate <change-dir>`（建 worktree；失败无 --force 会 STOP 要求人工处理） |
+| 记录测试结果（closing 必需） | `tf test record <change-dir> --from <runner输出文件或目录>`（支持 maven-surefire/jest/pytest，可 auto 识别；jest 须 `--json` 输出） |
+| 探测多仓库结构 | `tf repo-layout detect <项目根>`（识别 single/monorepo/multi-repo 并写入 `repo_layout` 配置） |
+| 隔离工作区 | `tf isolate <change-dir> [change-name]`（建 worktree；失败无 --force 会 STOP 要求人工处理） |
 | 收尾合并代码 | `tf deisolate <change-dir> --merge`（dirty 会阻断；merge commit 不 rebase） |
 | 沉淀一条经验 | `tf solutions capture --phase <p> --domain <d> --type <t> --severity <s> --summary "..."` |
 | 生成决策点审计报告 | `tf audit <change-dir>` |
@@ -386,56 +461,86 @@ tf doctor                              # 环境体检
 tf state init <dir>                    # 创建 change 状态（打戳 schema_version，计算三 hash）
 tf state check <dir>                   # artifacts_hash 一致性检查
 tf state get <dir> <field>             # 读字段
-tf state set <dir> <field> <value>     # 写白名单字段（dp_N_*、arch_design_*、skip 类等）
+tf state set <dir> <field> <value>     # 写白名单字段（41 个：dp_N_result/timestamp、arch_design_*、
+                                       # dp_a_*、skip 类、delegation_* 等）
 tf state rebuild <dir>                 # 重算三 hash（改完规划制品必跑）
 tf state transition <dir> <to-state>   # 状态转换（自动执行 guard 门禁）
 tf audit <dir>                         # 生成 decision-point-audit.md
 ```
 
-**不可手工 set 的字段**（CLI 有专用报错引导）：`state`（用 transition）、`test_result`（用 `tf test record`）、`schema_version`（仅 init 打戳的存量豁免键）。
+**字段可写性分三类**：
+
+- **白名单内可 set**（41 个）：`dp_{0,1,2,3,5,6,7}_result` 及其 `_timestamp`、`dp_0_decisions`/`dp_0_confirmed`、`dp_a_*`、`arch_design_*`、`arch_review_*`、`delegation_*`、`dp_4_glaf4_mode`/`dp_4_write_set_hash`、`compound_skipped`、`test_matrix_skipped(+reason)`、`tasks_skipped(+reason)`、`arch_merge_skipped(+reason)`、`workflow`、`batches_completed`、`spec_merged`。
+- **不可 set，但有专用报错引导**（3 个）：`state`（改走 `tf state transition`）、`test_result`（改走 `tf test record`）、`schema_version`（仅 `tf state init` 打戳，是存量豁免键）。
+- **其余一律不可 set**（通用报错 `Field '<x>' is not settable`）：包括 `artifacts_hash`/`contract_hash`/`test_matrix_hash`、`execution_mode`、**`dp_4_result`**（这个最容易误以为可设——它只能由 `tf execution plan --confirm` 程序化写入）。
 
 ### 执行计划
 ```bash
-tf execution recommend <dir>           # 证据驱动的执行模式推荐（DP-4 前置）
-tf execution plan <dir> --mode <m> --confirm --reason "..." --wave ...
+tf execution recommend <dir>           # 证据驱动的执行模式推荐（DP-4 前置，必须先跑）
+tf execution plan <dir> --mode <m> --confirm --reason "..." \
+    --wave <id>:<strategy>:<task,...>[:<depends-on,...>]   # strategy = parallel|serial
+    [--acknowledge-recommendation]     # 选了非推荐模式时必须加；跟随推荐却加了也会报错
 tf execution show <dir> [--json]       # 查看当前计划（current:true 才能开工）
-tf execution revise <dir> --mode sdd   # 修订计划（只能升级/重规划，不能降级）
-tf execution review <dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail
+tf execution revise <dir> --mode sdd --confirm --reason "..." --wave ...
+                                       # 修订计划（只能升级/重规划，不能降级）
+tf execution review <dir> --wave <id> --base <sha> --head <sha> \
+    --report <path> --verdict pass|fail [--repo <path>] \
+    [--tests-total N --tests-passed N --tests-failed N]
+                                       # --report 必须落在 <dir>/.superpowers/sdd/reviews/ 内；
+                                       # base 必须 ≠ head 且是 head 的祖先
 tf execution refresh-hash <dir>        # 不 bump revision 刷新 plan 内 hash
 ```
 
+> `recommend` 与 `plan` 是**强耦合**的一对：两次的 `--wave` 集合必须逐字一致，中间 artifacts_hash / contract_hash / workflow 任一变化即失效，需重跑 `recommend`。
+
 ### 测试与收尾
 ```bash
-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 基（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]
+tf test record <dir> --from <output|dir> [--runner auto|maven-surefire|jest|pytest]
+tf test-merge <dir> [--project-root <path>] [--dry-run]   # 测试矩阵 → docs/test-ledger/
+tf test-matrix-export <in.json> <out.md> [--change-id <id>] [--batch-id <id>]   # glaf4 矩阵桥接
+tf glaf4-evidence-export <run-dir> <out-file> [--mode <m>]  # glaf4 run 证据 → surefire 行，喂给 test record
+tf sync <dir>                          # delta specs 语义合并进主 spec 基（ADDED/MODIFIED/REMOVED/RENAMED；
+                                       # 幂等 + fail-closed，自动写 spec_merged；主基不存在时走拷贝）
+tf arch-merge <dir> [--project-root <path>] [--dry-run]   # 架构增量 → docs/architecture/
+tf prototype-sync <dir> [--source <ux-delta>] [--prototype-dir <path>]
+tf publish --prd|--arch|--changes <dir>|--all [--project-root <path>] [--push] [--dry-run]
 ```
 
 ### 隔离与恢复
 ```bash
-tf isolate <change-dir> [--force]      # worktree 隔离（build 前置）
+tf isolate <change-dir> [change-name] [--force]      # worktree 隔离（build 前置）
 tf deisolate <change-dir> [--merge] [--clean] [--force] [--json]
-tf checkpoint save|list|show           # 任务级恢复点
+tf checkpoint save|list|show           # 任务级恢复点（save 须 --task <id> --next <text>）
 tf handoff create|list|finish|resolve  # prototype/research/experiment 交接单
+                                       # create 须 --type --objective --expected-output --acceptance
+                                       # resolve 须 --decision accept|reject|defer
 tf prototype branch <prd-vN> | tf prototype deisolate <prd-vN> [--merge]
 ```
 
 ### 复利与架构
 ```bash
-tf solutions capture|index-gen|inject|promote
+tf solutions capture|index-gen|inject|promote|backfill
+                                       # backfill [--dry-run]：为存量条目补 title: 字段（检索依赖）
 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 注入各平台
-tf config [--resolve-model <profile>]          # mechanical/standard/strong/review 四档
+tf inject <dir> [--platforms claude,cursor,copilot,gemini|all]   # 按当前状态生成 phase-guard 注入（可逗号多选）
+tf config [--get <path>] [--set <path>=<value>] [--resolve-model <profile>]   # 四档 model profile
 tf runtime check-update | infer <dir> | guard ... | config ... | asset read <path>
 ```
 
+### 多仓库 / glaf4 委托 / 版本
+```bash
+tf repo-layout detect <root> [--json]  # 探测 single/monorepo/multi-repo + 代码仓库清单
+tf glaf4-delegation detect|confirm|verify-write-set|verify-tasks|record-partial|reset
+                                       # GLAF4 生产+测试委托协议（写集边界校验、状态位）
+tf version <semver> [--dry-run]        # 版本号同步到全部 manifest 与文本文件
+tf install-cursor | install-workbuddy | install-cline | install-kiro | install-windsurf |
+   install-qwen | install-amazon-q | install-roocode | install-continue | install-pi |
+   install-qoder | install-zcode       # 各平台部署（12 个）
+```
+
 ---
 
 ## 8. 产物目录全景
@@ -448,32 +553,43 @@ tf runtime check-update | infer <dir> | guard ... | config ... | asset read <pat
 │   ├── handoffs/                      # session-handoff 交接文档（gitignore）
 │   ├── feedback/                      # workflow-feedback 问题记录
 │   ├── conventions/                   # 项目规范（bootstrap 生成，按技术栈）
-│   ├── design-system/                 # 设计系统（base.md + b-end/c-end 变体 + preview.html）
+│   ├── design-system/                 # 设计系统（base 品牌层 + 端变体 + 派生件）
+│   │   ├── base.md                    # 品牌共享层（组件契约表权威真源）
+│   │   ├── <port>-end.md              # 端变体（b-end / c-end…）；主题变体在 variants/
+│   │   ├── primer.md                  # AI primer：组件白名单 + token 速查 + 硬规则（生成物）
+│   │   ├── preview.html               # 预览画廊
+│   │   ├── pending.md                 # 设计系统迭代待办（closing 只读检查）
+│   │   └── showcase/                  # 展示板（可选）
 │   ├── arch-state.json                # 架构基线打戳（tf arch init，存量豁免键）
-│   └── team-flow.config.json          # 项目配置（v0.26+ 迁入 .team-flow/ 规划中）
+│   └── team-flow.config.json          # 项目配置（查找第一优先；仓库根的旧位置仅作 legacy 回退）
 │
 ├── requirement/vN/                    # 产品级需求制品（vN = PRD 迭代版本）
 │   ├── prd.md                         # PRD（frontmatter 冻结态是单一真相源）
 │   ├── plan.md                        # 实施计划（change 拆分+DAG+技术方向，无接口清单）
+│   ├── detail-ledger.md               # 功能细节澄清台账（§8.4 契约级，v0.47.0）
 │   ├── business-analysis.md           # 业务场景/流程分析
+│   ├── dialogue-log.md                # 澄清过程记录
 │   ├── prd-completeness-review.md     # PRD 完整性自动评审报告
 │   ├── prototype-auto-review.md       # 原型自动评审报告
 │   └── change-split-audit.md          # 拆分质量审计报告
 │
 ├── prototype/                         # 全局唯一原型（独立 git 仓库，按 PRD 版本分支）
-│   ├── index.html / pages/ / components/ / assets/
-│   ├── design-tokens.css / design-system.md / flow.md
+│   ├── index.html / pages/ / components /
+│   ├── assets/design-tokens.css + design-tokens.js
+│   └── flow.md
+│   （设计系统不在此目录——权威位置是 .team-flow/design-system/）
 │
 ├── docs/
 │   ├── architecture/                  # L1 全局架构当前态（arch-merge 回写，权威）
 │   │   ├── ARCHITECTURE.md            # marker 区 = 所有已合并 change 增量的投影
 │   │   ├── DATABASE.md / PHYSICAL-MODEL.md / schema-baseline.sql / API-INDEX.md / INDEX.md
+│   │   │                              # ↑ 生成式制品，由 arch-merge 重建，勿手写
 │   │   ├── CONCEPTS.md                # 领域词汇表
-│   │   ├── baseline.md                # bootstrap 产出的项目基线画像
+│   │   ├── baseline.md                # bootstrap 产出的项目基线画像（As-Is 叙述唯一载体）
 │   │   ├── changelog/                 # DDL/migration 归档
 │   │   └── iterations/vN/architecture.md   # L3 迭代快照（预测态，收尾标 archived）
-│   ├── solutions/                     # 复利经验库（INDEX.md ≤150 条 + 分阶段目录）
-│   └── test-ledger/                   # 全局测试台账（test-merge 回写）
+│   ├── solutions/                     # 复利经验库（INDEX.md ≤150 条 + 按 phase 分子目录）
+│   └── test-ledger/                   # 全局测试台账（test-merge 回写；含 baselines/、changelog/、INDEX.md）
 │
 ├── specs/<capability>/spec.md         # 主 spec 基（spec-merger 合并 delta 的目标）
 │
@@ -486,8 +602,9 @@ tf runtime check-update | infer <dir> | guard ... | config ... | asset read <pat
 │   ├── execution-contract.md          # 执行契约（contract_hash）
 │   ├── test-matrix.md                 # 测试矩阵（12 列，test_matrix_hash）
 │   ├── learnings.md                   # 复利经验（closing 门禁要求或显式 skip）
-│   └── .superpowers/                  # 运行时 overlay（审查报告已迁至 sdd/reviews/）
-│       ├── sdd/                       # execution-plan.json / reviews/ / checkpoints / progress.md
+│   └── .superpowers/                  # 运行时 overlay（审查报告落在 sdd/reviews/）
+│       ├── sdd/                       # execution-plan.json / execution-recommendation.json /
+│       │                              # reviews/<waveId>.json / checkpoints / handoffs/ / progress.md
 │       └── test-evidence/             # tf test record 的 runner 原始输出证据
 │
 ├── .worktrees/                        # worktree 隔离区（tf isolate 创建，gitignore）
@@ -503,7 +620,7 @@ tf runtime check-update | infer <dir> | guard ... | config ... | asset read <pat
 
 ### Q1：门禁 BLOCK 了我，怎么看原因、怎么解？
 
-转换失败时 CLI 会逐条打印 `[dimension] failure` 及具体原因。也可预检：
+转换失败时 CLI 会逐条打印 `[FAIL] <dimension>: <failure>` 及具体原因。也可预检：
 
 ```bash
 tf runtime guard check <change-dir> <from> <to> --json
@@ -515,15 +632,15 @@ tf runtime guard check <change-dir> <from> <to> --json
 |---------|------|------|
 | `execution-contract.md is stale: artifacts hash mismatch` | 规划制品改了，契约没重建 | 回 bridging 重跑 contract-builder，或 `tf state rebuild` 后重新生成 |
 | `no programmatic test evidence recorded` | 没有 `tf test record` 记录 | 跑测试 → `tf test record <dir> --from <输出文件>` |
-| `recorded-by` 校验失败 | 手工写了 test_result | 手工通道已关闭，必须走 tf test record；或显式 skip+理由 |
-| `test matrix skip reason missing` | skip 了矩阵没写理由 | `tf state set test_matrix_skip_reason "<理由>"` |
-| `tasks skip reason missing` | skip 了 tasks.md 没写理由 | `tf state set tasks_skip_reason "<理由>"` |
+| `test_result must be recorded by 'tf test record'` | 手工写了 test_result | 手工通道已关闭，必须走 tf test record；或显式 skip+理由 |
+| `test_matrix_skipped=true requires test_matrix_skip_reason` | skip 了矩阵没写理由 | `tf state set <dir> test_matrix_skip_reason "<理由>"` |
+| `tasks_skipped=true requires tasks_skip_reason` | skip 了 tasks.md 没写理由 | `tf state set <dir> tasks_skip_reason "<理由>"` |
 | `tasks_skipped is only valid for hotfix/tweak` | full/auto 路径置了 skip 键 | 产出 tasks.md，或 `tf state set <dir> workflow <hotfix\|tweak>` 先声明模式 |
-| `dp_3_result` / `dp_4_result` 缺失 | DP 决策未记录 | 回到对应决策点完成确认 |
+| `DP-3 ... is not recorded` / `DP-4 (dp_4_result) is not recorded` | DP 决策未记录 | 回到对应决策点完成确认；**dp_4_result 只能由 `tf execution plan --confirm` 写** |
 | `plan revision <N>` 不匹配 | DP-4 记录没引用当前计划版本 | 重新 `tf execution plan`（或 revise） |
-| `base == head` review 被拒 | 空 diff 审查 | 用真实的 wave 起止 commit |
+| `Review receipt base must differ from head` | 空 diff 审查 | 用真实的 wave 起止 commit（base 须是 head 的祖先） |
 | `Unknown transition` | 非法状态转换对 | 状态机闭合，按合法路径走（如需放弃用 →abandoned） |
-| hook block："implementation editing is limited to build states" | 非 build 态在 change 目录外写实施代码 | 推进工作流到 approved-for-build/executing/debugging；change 目录内制品写永远放行 |
+| hook block：`implementation edits ... OUTSIDE the change directory are blocked while the change is in state '<state>'` | 非 build 态在 change 目录外写实施代码 | 推进到 approved-for-build/executing/debugging；change 目录内制品写永远放行 |
 
 ### Q2：存量 change / 老项目会被新门禁卡死吗？
 
@@ -533,13 +650,20 @@ tf runtime guard check <change-dir> <from> <to> --json
 
 ### Q3：我真的要跳过某个门禁怎么办？
 
-每条门禁都有合法逃生舱，但**必须显式+留痕**：
+**不是每条门禁都有逃生舱**，分两类：
+
+**可豁免**（显式登记，留痕可审计）：
 - 测试矩阵：`test_matrix_skipped=true` + `test_matrix_skip_reason`
 - tasks.md：`tasks_skipped=true` + `tasks_skip_reason`（**仅 hotfix/tweak**；full/auto 置键会被 `tasks-complete` 直接 FAIL——先 `tf state set <dir> workflow <hotfix|tweak>` 声明模式，或产出 tasks.md）
-- 复利：`tf state set compound_skipped true`
-- 架构 skip：物化 `iterations/vN/SKIPPED` 标记 + 理由
-- 隔离失败：`--force`（会警告）
-- 偏离执行推荐：`--acknowledge-recommendation`
+- 复利：`tf state set <dir> compound_skipped true`（不要求理由）
+- 架构增量回写：`arch_merge_skipped=true` + `arch_merge_skip_reason`（确无增量可回写时）
+- change 级架构判断门：`arch_design_decision=skipped` + `arch_design_reason`（由 architecture-design 子代理写）
+- 产品级架构阶段：物化 `iterations/vN/SKIPPED` 标记 + 理由
+- 存量豁免：`schema_version` 缺失（= 老 change）、`arch_baseline` 缺失（= 老项目，WARN 不 FAIL）
+
+**不可豁免**（只能补产物 / 补决策）：`dp3-approved`、`dp-gate-passed`、`artifacts-exist`、`schema-valid`、`contract-fresh` / `contract-current`、`execution-plan-ready`、`execution-reviews-passed`、`delegation-status`。
+
+> `--force`（属 `tf isolate` / `tf deisolate --merge`）与 `--acknowledge-recommendation`（属 `tf execution plan`）**不是 guard 门禁的逃生舱**，别混为一谈。
 
 不要用手工编辑 `.team-flow.yaml` 的方式绕——writeState 会拒绝非法值，hook 永远拦截该文件。
 
@@ -588,7 +712,7 @@ tf runtime guard check <change-dir> <from> <to> --json
 2. ⛔ 非 build 态写实施代码（Claude Code 硬拦；其他平台靠自觉+转换门禁兜底）
 3. ⛔ 绕过 DP-3 开始实施（无契约批准 = 非法开工）
 4. ⛔ 手工伪造 test_result（通道已关闭，只认 tf test record）
-5. ⛔ 主代理直接改子代理的产物（违反 Artifact Ownership，修改要经 SendMessage 回原子代理）
+5. ⛔ 主代理直接改子代理的产物（违反 Artifact Ownership；v0.39.0 起更严：主代理不得直接 Edit/Write `changes/<name>/` 或 `.worktrees/` 下**任何**文件，改动一律经 SendMessage 回原子代理）
 6. ⛔ 用 rebase 合并收尾代码（规范是 merge commit，保真实历史可回退）
 7. ⛔ 空 diff 记 review receipt（base==head 被 CLI 拒绝）
 
@@ -599,13 +723,19 @@ tf runtime guard check <change-dir> <from> <to> --json
 | 平台 | 安装方式 | SessionStart 注入 | 硬拦截（PreToolUse） | 门禁生效形式 |
 |------|---------|------------------|---------------------|-------------|
 | Claude Code | Marketplace / plugin.json | ✅ | ✅ | hook + guard + 规则 |
+| GitHub Copilot CLI | Marketplace | ✅ | ❌ | SessionStart + copilot-instructions |
 | Cursor | 一键脚本 | ✅ | ❌ | SessionStart + phase-guard.mdc |
 | Codex CLI/App | 插件目录 / release tag | ❌ | ❌ | phase-guard 规则 |
 | Gemini CLI | gemini-extension.json | ❌ | ❌ | GEMINI.md marker 注入 |
 | OpenCode | JS plugin | ❌ | ❌ | bootstrap 注入 |
+| WorkBuddy | `tf install-workbuddy` | ❌ | ❌ | rules/phase-guard.md |
+| ZCODE | `tf install-zcode` | ❌ | ❌ | `.zcode/rules/` |
+| Trae IDE / TRAE Work | `.trae/skills` / zip / marketplace | ❌ | ❌ | 无 rules 目录 |
 | Cline/Kiro/Windsurf/Qwen/Amazon-Q/Roo/Continue/Pi/Qoder | `tf install-<平台>` | ❌ | ❌ | phase-guard 规则文件 |
 
-> 所有平台的 skills/agents/CLI 能力一致，差异只在守卫强度。非 Claude Code 平台建议：关键状态转换后手动 `tf inject <change-dir>` 刷新 phase-guard 规则文件。
+> 所有平台的 skills/agents/CLI 能力一致，差异只在守卫强度。共 **19 个平台**——上表末行含 Cline、Kiro、Windsurf、Qwen、Amazon Q、Roo、Continue、Pi、Qoder 九个；`Codex CLI` 与 `Codex App` 是两个独立平台（同一行）；Trae IDE 与 TRAE Work 计一个。
+>
+> **关于 `tf inject`**：它只支持 `claude,cursor,copilot,gemini` 四个平台（可用逗号一次传多个，或 `all`；其余平台传参会报 `Unsupported platform(s)`）。这四家在关键状态转换后可手动 `tf inject <change-dir>` 刷新规则；**其他平台的 phase-guard 规则是安装时静态写入的**（不含当前 state），状态纪律靠每次会话让 agent 读 `.team-flow.yaml`。
 
 ---
 
@@ -622,4 +752,4 @@ tf runtime guard check <change-dir> <from> <to> --json
 
 ---
 
-*本文档基于 v0.44.0 源码全量分析产出。发现与实际行为不符，请 `/team-flow:workflow-feedback` 反馈——这正是本插件的演进方式。*
+*本文档基于 v0.60.0 源码全量核对产出（2026-09-13 同步）。发现与实际行为不符，请 `/team-flow:workflow-feedback` 反馈——这正是本插件的演进方式。*