@xulthekl/team-flow 0.49.0 → 0.50.0

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

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.49.0",
+  "version": "0.50.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.49.0",
+  "version": "0.50.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.49.0"
+    "version": "0.50.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.49.0",
+  "version": "0.50.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.49.0"
+    "version": "0.50.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.49.0",
+      "version": "0.50.0",
       "source": ".",
       "author": {
         "name": "LT",

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to `team-flow` will be documented in this file.
 
 The format loosely follows Keep a Changelog.
 
+## [0.50.0] - 2026-09-09
+
+### Fixed（hotfix 路径死锁 + 轻量路径仪式成本）
+
+设计来源：`docs/architecture-api-db-design-enhancement-v0.22.md` §85-§88（2026-09-09，fytx-gateway-parent 3 条 workflow-feedback：20260909-103500-guard / 20260909-103600-cli-command / 20260909-112755-sop-flow）
+
+**根因簇 R1 — hotfix/tweak 产物归属链断裂**（closing 死锁）
+
+- **可审计豁免**：`executing:closing` 的 `tasks-complete` 维度对 hotfix/tweak 必然 FAIL（跳过 spec-writer，tasks.md 无原生产出者），与 SKILL「may skip tasks.md」冲突且无豁免路径 → 新增 `tasks_skipped` + `tasks_skip_reason`（与 `test_matrix_skipped` 同构的可审计豁免范式），存量 change 走 legacy 豁免；新增 `scripts/guard/checks/tasks-gate-exemptions.mjs` 作为判定唯一真相源（`tasks-complete.mjs`）
+- **字段贯通**：`state-loader`（BUILTIN_DEFAULTS + writeState 序列化）、`cmd-state`（SETTABLE_FIELDS）、`tf doctor` 卫生巡检（skip 无理由 + 引用文件缺失）三处同步
+- **模式门控**（P4 终检补，LT 2026-09-09 决策）：`tasks_skipped` 仅对 hotfix/tweak 合法——full/auto 置键直接 FAIL 并引导两条出路（产出 `tasks.md` / 先 `tf state set <dir> workflow hotfix|tweak`），消除「文档说不允许、代码却放行」的口径分裂；`auto` 归一化为 full（与 `cmd-state.mjs:163` 同口径，安全侧默认）
+- **横展**：tweak 路径存在同类死锁，一并修；`docs/decision-points.md` 补录 DP-A（v0.29.0 引入时遗漏）并新增「确认点合并」节
+
+**根因簇 R2 — CLI 输入约束未上浮到接口层**（两处）
+
+- **jest 需 `--json`**：解析器要求 JSON 输出但 help/SKILL 未声明 → 顶层 help + build-executor SKILL 补声明
+- **`tf execution review --report` 须在 change overlay 内**：路径约束仅存在于报错文案 → 顶层 help + 5 处 SKILL 补声明（横展 code-reviewer / execution-modes / routing-rules）
+- **清单化扫描**：`scripts/lib/*.mjs` 全部输入校验点逐条核对文档声明，其余约束或报错自解释、或已声明，不额外补文档
+
+**根因簇 R3 — 轻量规定不可执行**
+
+- **contract-builder `## Hotfix Mode` 重写**：适用判据 3 条 + 轻契约骨架 6 章节（Intent Lock / 锁定值表 / 范围栅栏 / Execution Batch / Test Matrix / Approval Gate）+ 移出清单 + 代码锚点 + 质量不变量
+- **release-archivist `## Lightweight Closure` 补回写链前置判据**：arch-merge / prototype-sync / test-merge / compound promotion 四项「何时适用」表，消除 `skip silently` 的适用性歧义（`:164`/`:196` 加回指）
+- **Hotfix/Tweak Exemption 拆块**：hotfix/tweak 块与 full 特例块分离，避免 full 流程被卷入 skip 引导
+
+**根因簇 R4 — 仪式成本未按风险分级**
+
+- **确认点合并**：hotfix 6 个确认点（DP-0 / DP-A / DP-3 / G4 / DP-4 / DP-7）合并为 3 组（变更基线 / 实施授权 / 归档）；先修正 DP-0 口径矛盾（保留 DP-0，`:170` 表述修正）；`arch_design_decision == required` 时 DP-A 不合并；门禁维度与 state 字段不变——减少的是交互轮次，不是门禁强度
+- **`tf arch precheck` 证据工具**：新增 `scripts/lib/arch-precheck.mjs`——输出确定性证据（架构关键词的变更语境命中 / 否定命中 / 仅提及 + 改动文件分类），**退出码恒 0**；architecture-design 据此走 Fast Path（`signal: none` 时只读 brief + precheck 输出，不读全量 `docs/architecture/`），**判断权仍在子代理**（证据与 brief 不符必须回退完整路径）
+
+### Tests & Tooling
+
+- 新增 `tests/lib/guard-tasks-gate.test.mjs`（12 例，含 5 例模式门控）、`tests/lib/arch-precheck.test.mjs`（7 例）
+- `tests/lib/cmd-doctor.test.mjs` 补 `checkChangeTestGates()` 覆盖（9 例，此前该函数无任何测试）
+- 新增 `npm run lint:skills`（此前 lint 脚本存在但未接入任何 npm script）；修正 `behavior-consistency` 规则误报（`route to \`references/...\`` 被当作 skill 名，error 级），6 error → 5 error（余下 5 项为既有 SKILL.md 超行数，记入待办）
+
 ## [0.49.0] - 2026-09-09
 
 ### Fixed（execution plan 冻结边界与复利链路修复）

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

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.49.0**。
+当前发布版本：**v0.50.0**。
 
 ---
 
@@ -809,4 +809,4 @@ Checkpoint 是任务级恢复上下文。`result-ready` handoff 在继续受影
 
 推荐流程：`exploring -> specifying -> bridging -> approved-for-build -> execution plan -> executing -> closing`
 
-hotfix 快速路径：`exploring -> bridging -> approved-for-build -> executing`。hotfix 可以跳过完整的 `proposal.md`、`design.md`、`tasks.md`、`specs/`，但仍然必须先生成一份新的最小 `execution-contract.md`，并完成 DP-3 批准后才能开始实现。
+hotfix 快速路径：`exploring -> bridging -> approved-for-build -> executing`。hotfix 可以跳过完整的 `proposal.md`、`design.md`、`specs/`，但仍然必须先生成一份新的最小 `execution-contract.md`，并完成 DP-3 批准后才能开始实现。`tasks.md` 不允许静默缺失（v0.22 §85）：须由 contract-builder 显式登记 `tasks_skipped=true` + `tasks_skip_reason`，或一并产出最小任务清单。

package/README.md

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

package/agents/architecture-design.md

@@ -37,7 +37,7 @@ You are an independent architecture designer. You read the change brief, plan, e
 | `mode` | `change`（默认，workflow-start 五项检查）\| `product`（v0.36.0，S3.5 产品级架构设计） |
 | `change_brief_path` | change-brief.md 路径（scope / AC / 技术方向；change 模式必填） |
 | `plan_path` | requirement/vN/plan.md 路径（高阶技术设计段） |
-| `snapshot_path` | docs/architecture/iterations/vN/architecture.md（产品级快照；change 模式主输入，product 模式产出目标） |
+| `snapshot_path` | docs/architecture/iterations/vN/architecture.md（产品级快照；change 模式主输入，product 模式产出目标；**Fast Path 命中时不传**） |
 | `specs_dir` | changes/<name>/specs/ 路径（现有规格，如有） |
 | `global_arch_dir` | docs/architecture/ 路径（As-Is 基线） |
 

package/agents/code-reviewer.md

@@ -15,7 +15,7 @@ You are an independent Code Reviewer. You review code changes for quality, spec
 
 ## Iron Law
 
-You are a reviewer. You did NOT write the code. You read the implementation, compare it against specs/requirements, check code quality, and produce a verdict with findings. You MUST write the review report to disk at the path specified by the orchestration layer (typically `changes/<name>/code-review.md`). Do NOT modify any implementation files — only write the review report.
+You are a reviewer. You did NOT write the code. You read the implementation, compare it against specs/requirements, check code quality, and produce a verdict with findings. You MUST write the review report to disk at the path specified by the orchestration layer — it MUST resolve inside the change review overlay `<change-dir>/.superpowers/sdd/reviews/` (v0.22 §86: the CLI rejects any path outside it). Do NOT modify any implementation files — only write the review report.
 
 ## Inputs
 

package/docs/README_en.md

@@ -126,7 +126,7 @@ npm install -g team-flow
 
 ### Version
 
-- Current: `v0.49.0`
+- Current: `v0.50.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)
@@ -279,7 +279,7 @@ not implemented, so this documentation does not claim `/tf:*` commands.
 
 ### Fast Paths (hotfix / tweak)
 
-- **hotfix** — ≤2 files, no new modules → `exploring -> bridging -> approved-for-build -> executing`. It may skip full planning artifacts such as `proposal.md`, `design.md`, `tasks.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md` plus DP-3 approval before implementation
+- **hotfix** — ≤2 files, no new modules → `exploring -> bridging -> approved-for-build -> executing`. It may skip full planning artifacts such as `proposal.md`, `design.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md` plus DP-3 approval before implementation. `tasks.md` is not silently skipped (v0.22 §85): contract-builder records an explicit `tasks_skipped=true` + `tasks_skip_reason`, or produces a minimal task list
 - **tweak** — ≤4 files, config/docs only → skip planning + bridging, direct edit
 
 ---

package/docs/artifact-contract.md

@@ -45,6 +45,8 @@ Defines:
 - dependency-aware work breakdown
 - completion units that become named execution waves in the execution plan
 
+> **hotfix/tweak 豁免（v0.22 §85）**：该路径跳过 spec-writer，`tasks.md` 默认显式跳过（`tasks_skipped=true` + `tasks_skip_reason`）——**hotfix 由 contract-builder 写入，tweak 由主代理写入**（tweak 不经过 contract-builder）；若 change 需要任务清单，归属 contract-builder 产出。closing 的 `tasks-complete` 门禁按该键豁免。
+
 ### `execution-contract.md`
 
 Defines:

package/docs/decision-points.md

@@ -74,6 +74,16 @@
 - **预期输出**：用户确认归档并批准 delta spec 合并，或要求调整合并范围后再执行
 - **关联 skill**：`team-flow:release-archivist`
 
+## DP-A: 架构设计确认（v0.29.0 §37）
+
+- **编号**：DP-A
+- **名称**：架构设计用户确认门
+- **触发条件**：architecture-design 子代理返回判定结果 + auto-review 完成后、路由 spec-writer 前
+- **所需输入**：架构决策摘要（decision + reason + artifacts）、auto-review verdict
+- **预期输出**：用户确认接受（`dp_a_result: confirmed`）或要求调整（`adjustment_requested`——须经 SendMessage 恢复原子代理修改后重新确认）
+- **关联 skill**：`team-flow:workflow-start`（编排层把关；**非状态转换 guard 维度**）
+- **状态字段**：`dp_a_result` / `dp_a_timestamp` / `dp_a_adjustments`
+
 ## 决策点与 Skill 映射总览
 
 | 编号 | 名称 | 关联 Skill | 阶段 |
@@ -86,3 +96,16 @@
 | DP-5 | 调试升级 | `team-flow:bug-investigator` | 执行 |
 | DP-6 | 验证失败 | `team-flow:release-archivist` | 收尾 |
 | DP-7 | 归档确认 | `team-flow:release-archivist` | 收尾 |
+| DP-A | 架构设计确认 | `team-flow:workflow-start` | 架构 |
+
+## 确认点合并（v0.22 §88.3.1）
+
+以下三组可合并为**一次** AskUserQuestion——减少的是用户交互轮次，**门禁强度不变**（`dp_*` 字段仍须写入，guard 维度不豁免）：
+
+| 合并组 | 触发条件 |
+|--------|----------|
+| DP-0 + DP-A | `arch_design_decision == skipped` |
+| DP-3 + G4 + DP-4 | 契约已产出且 hash 有效 |
+| DP-7 + 代码落地 + G5 | 恒成立 |
+
+`arch_design_decision == required` 时 DP-A 必须独立（用户需单独审架构产物）。

package/docs/state-machine.md

@@ -157,6 +157,6 @@ If the contract changed, the artifacts changed.
 ## Fast-Path Notes
 
 - `hotfix` follows `exploring -> bridging -> approved-for-build -> executing`.
-- `hotfix` may skip full planning artifacts such as `proposal.md`, `design.md`, `tasks.md`, and `specs/`.
+- `hotfix` may skip full planning artifacts such as `proposal.md`, `design.md`, and `specs/`; `tasks.md` requires an explicit `tasks_skipped=true` + `tasks_skip_reason` (v0.22 §85) rather than a silent skip. The key is rejected for `full`/`auto` workflows — declare the mode first (`tf state set <dir> workflow hotfix|tweak`) or produce `tasks.md`.
 - `hotfix` still requires a fresh minimal `execution-contract.md` and explicit DP-3 approval before implementation.
 - `tweak` remains the only path that can jump directly from `exploring` to `approved-for-build`.

package/docs/usage-guide.md

@@ -1,6 +1,6 @@
 # team-flow 使用说明（研发团队版）
 
-> 版本锚点：v0.47.0（26 skills + 17 agents）· 更新日期：2026-08-21
+> 版本锚点：v0.50.0（26 skills + 17 agents）· 更新日期：2026-09-09
 > 读者：使用 team-flow 做日常研发的工程师。不需要你懂插件内部实现，只需要照着路径走。
 > 配套文档：安装细节见 [INSTALL.md](../INSTALL.md)；状态机细节见 [state-machine.md](state-machine.md)；决策点细节见 [decision-points.md](decision-points.md)；平台差异见 [platform-matrix.md](platform-matrix.md)。
 
@@ -164,7 +164,7 @@ workflow-start 在初始化时自动推断（`tf runtime infer`），你也可
 | **hotfix** | ≤2 任务、≤2 文件、不动 schema/API | 跳过需求探索和规划制品，最小契约仍需 DP-3 批准 | test-matrix-complete、执行计划回执 |
 | **tweak** | ≤4 任务的纯配置/文档类 | 直接进 approved-for-build，直接编辑 | 执行计划、逐 wave 审查回执、测试矩阵 |
 
-**注意**：hotfix/tweak 豁免测试矩阵时**必须显式 skip 并写明理由**（`tf state set test_matrix_skipped true` + `test_matrix_skip_reason`），门禁不接受无理由跳过。架构设计判断门（五项检查）**两种模式都不豁免**。
+**注意**：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`），门禁不接受无理由跳过。架构设计判断门（五项检查）**两种模式都不豁免**。
 
 ### 4.3 决策点（DP）——什么时候需要你拍板
 
@@ -427,6 +427,7 @@ tf prototype branch <prd-vN> | tf prototype deisolate <prd-vN> [--merge]
 tf solutions capture|index-gen|inject|promote
 tf arch init [--mode reconstruction|design]   # 项目架构基线打戳（存量豁免键）
 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 runtime check-update | infer <dir> | guard ... | config ... | asset read <path>
@@ -482,8 +483,7 @@ 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）
-│   ├── code-review.md / *-review.md   # 各审查报告
-│   └── .superpowers/                  # 运行时 overlay
+│   └── .superpowers/                  # 运行时 overlay（审查报告已迁至 sdd/reviews/）
 │       ├── sdd/                       # execution-plan.json / reviews/ / checkpoints / progress.md
 │       └── test-evidence/             # tf test record 的 runner 原始输出证据
 │
@@ -514,6 +514,8 @@ tf runtime guard check <change-dir> <from> <to> --json
 | `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 "<理由>"` |
+| `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 决策未记录 | 回到对应决策点完成确认 |
 | `plan revision <N>` 不匹配 | DP-4 记录没引用当前计划版本 | 重新 `tf execution plan`（或 revise） |
 | `base == head` review 被拒 | 空 diff 审查 | 用真实的 wave 起止 commit |
@@ -530,6 +532,7 @@ tf runtime guard check <change-dir> <from> <to> --json
 
 每条门禁都有合法逃生舱，但**必须显式+留痕**：
 - 测试矩阵：`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`（会警告）

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

package/hooks/session-start

@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
-# v0.49.0: auto-sync CLI version with plugin version
+# v0.50.0: auto-sync CLI version with plugin version
 set -e
 
 # ═══════════════════════════════════════════════════════════════
 # Plugin version (update this when releasing new versions)
 # ═══════════════════════════════════════════════════════════════
-PLUGIN_VERSION="0.49.0"
+PLUGIN_VERSION="0.50.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.49.0.
+Current version: v0.50.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.49.0",
+  "version": "0.50.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",
@@ -18,6 +18,7 @@
     "test:e2e:plugin-sync": "node tests/e2e/scripts/plugin-sync.mjs",
     "test:e2e:llm": "TF_E2E_LLM=1 node --test --test-concurrency=1 tests/e2e/workflow/*.test.mjs",
     "validate": "node scripts/validate-artifacts",
+    "lint:skills": "node scripts/lint/lint-skills.mjs",
     "version": "node scripts/team-flow.mjs version $npm_new_version && node scripts/check-version-consistency.mjs && git add -A",
     "check-versions": "node scripts/check-version-consistency.mjs",
     "setup-hooks": "node scripts/install-git-hooks.mjs"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.49.0",
+  "version": "0.50.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/tasks-complete.mjs

@@ -1,15 +1,51 @@
 // scripts/guard/checks/tasks-complete.mjs — verify all tasks in tasks.md are checked off
+//
+// v0.22 §85（workflow-feedback 20260909-103500-guard）：新增 legacy 与显式 skip 两条豁免。
+// 修复前 hotfix/tweak（跳过 spec-writer，无 tasks.md）在 executing:closing 必然 FAIL，
+// 与 workflow-start SKILL 的 "may skip tasks.md" 表述冲突，导致 closing 死锁。
 import fs from 'node:fs';
 import path from 'node:path';
+import { readState } from '../../lib/state-loader.mjs';
+import {
+  isLegacyChange,
+  fullWorkflowSkipViolation,
+  tasksSkipMissingReason,
+  TASKS_SKIP_REASON_HINT,
+  TASKS_SKIP_FULL_FORBIDDEN_HINT,
+} from './tasks-gate-exemptions.mjs';
 
 /**
  * Check that tasks.md has no unchecked items and at least one completed item.
- * Returns { pass, failures[] }.
+ * Returns { pass, failures[], reason? }.
  */
 export function checkTasksComplete(changeDir) {
+  const state = readState(changeDir);
+
+  if (isLegacyChange(state)) {
+    return { pass: true, failures: [], reason: 'legacy change — initialized before v0.32.0' };
+  }
+
+  if (state.tasks_skipped === 'true') {
+    // v0.22 §85.4（LT 2026-09-09）：full/auto 不允许跳过——tasks.md 是 spec-writer 核心产物。
+    // 与 contract-builder SKILL「full 不得设置 tasks_skipped」及 usage-guide 的口径一致。
+    if (fullWorkflowSkipViolation(state)) {
+      return { pass: false, failures: [TASKS_SKIP_FULL_FORBIDDEN_HINT] };
+    }
+    if (tasksSkipMissingReason(state)) {
+      return { pass: false, failures: [TASKS_SKIP_REASON_HINT] };
+    }
+    return { pass: true, failures: [], reason: `explicitly skipped: ${state.tasks_skip_reason}` };
+  }
+
   const tasksPath = path.join(changeDir, 'tasks.md');
   if (!fs.existsSync(tasksPath)) {
-    return { pass: false, failures: ['tasks.md: missing'] };
+    return {
+      pass: false,
+      failures: [
+        'tasks.md: missing — produce it, or skip explicitly '
+        + '(tf state set <dir> tasks_skipped true && tf state set <dir> tasks_skip_reason "<why>")',
+      ],
+    };
   }
 
   const content = fs.readFileSync(tasksPath, 'utf-8');
@@ -28,4 +64,4 @@ export function checkTasksComplete(changeDir) {
   }
 
   return { pass: true, failures: [] };
-}
+}

package/scripts/guard/checks/tasks-gate-exemptions.mjs

@@ -0,0 +1,49 @@
+// scripts/guard/checks/tasks-gate-exemptions.mjs — v0.22 §85 tasks-complete 门禁豁免
+//
+// 背景（workflow-feedback 20260909-103500-guard）：
+// hotfix/tweak 跳过 spec-writer（workflow-start SKILL.md:172/173），tasks.md 的任务文本
+// 无原生产出者；而 guard 的 executing:closing 仍考核 tasks-complete（guard.mjs:75/82）。
+// 修复前该矛盾导致 closing 死锁，只能由编排层补录 tasks.md 绕过。
+//
+// 本模块与 test-gate-exemptions.mjs 同构：显式跳过优于静默豁免（v0.13 §48 原则），
+// 跳过必须附理由才放行；存量 change（无 schema_version）沿用 legacy 豁免。
+import { isLegacyChange } from './test-gate-exemptions.mjs';
+
+export { isLegacyChange };
+
+/** v0.22 §85：显式跳过 tasks.md 且理由非空（可审计豁免）。 */
+export function hasExplicitTasksSkip(state) {
+  return state?.tasks_skipped === 'true'
+    && typeof state?.tasks_skip_reason === 'string'
+    && state.tasks_skip_reason.trim().length > 0;
+}
+
+/** skip 已置但理由缺失 → 门禁拒绝并引导补理由。 */
+export function tasksSkipMissingReason(state) {
+  return state?.tasks_skipped === 'true' && !hasExplicitTasksSkip(state);
+}
+
+/**
+ * v0.22 §85.4（LT 2026-09-09 决策）：`tasks_skipped` 仅对 hotfix/tweak 合法。
+ * full 的 tasks.md 是 spec-writer 核心产物，必然产出——缺失即流程异常，应 FAIL 暴露而非豁免掩盖。
+ * `auto`/缺失归一化为 full（与 cmd-state.mjs:163 的 auto→full 归一化同口径，安全侧默认）。
+ * 无存量风险：tasks_skipped 是 v0.50.0 新字段。
+ */
+export function isFullWorkflow(state) {
+  const workflow = state?.workflow;
+  return workflow == null || workflow === '' || workflow === 'auto' || workflow === 'full';
+}
+
+/** full/auto 置了 skip → 拒绝，并给出两条可操作出路（不是死锁）。 */
+export function fullWorkflowSkipViolation(state) {
+  return state?.tasks_skipped === 'true' && isFullWorkflow(state);
+}
+
+export const TASKS_SKIP_REASON_HINT =
+  'tasks_skipped=true requires tasks_skip_reason — record it: '
+  + "tf state set <dir> tasks_skip_reason '<why this change needs no tasks.md>'";
+
+export const TASKS_SKIP_FULL_FORBIDDEN_HINT =
+  'tasks_skipped is only valid for hotfix/tweak — full workflow must produce tasks.md. '
+  + 'Either produce tasks.md, or, if this change is truly a hotfix/tweak, '
+  + 'declare the mode first: tf state set <dir> workflow <hotfix|tweak>';

package/scripts/lib/arch-precheck.mjs

@@ -0,0 +1,190 @@
+// scripts/lib/arch-precheck.mjs — tf arch precheck：架构判断门的确定性证据工具（v0.22 §88.3.2）
+//
+// 定位：**证据工具，不是判断者**。本命令只输出"架构信号命中情况"，
+// 判断仍归 architecture-design 子代理（v0.9 §26 的独立性不变）。
+// 退出码恒为 0 —— 不阻断流程，也不替代判断。
+//
+// 动机（workflow-feedback 20260909-112755）：hotfix 对表现层文案改动跑完整架构门
+// 消耗 41,864 tk，结论必然 skipped。让子代理在 signal=none 时只读 brief + 本命令输出
+// （不读全量 docs/architecture/）可大幅降本，同时保留独立判断与回退能力。
+//
+// 设计约束（H1 实测校准）：
+//   - 关键词须为**高置信度**短语——裸 `schema` / `api` 会误命中测试矩阵术语（"schema 覆盖声明"）
+//   - 否定表述须识别——"不动 filter.args" / "无聚合" 是**负向**证据，不能计为命中
+//   - 文件提取须去噪——`node_modules/` 引用非改动文件；同名文件按最完整路径去重
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 架构关键词表（对应 architecture-design SKILL 五项检查 + 配置契约 key）。 */
+const ARCH_KEYWORDS = [
+  // 1 聚合
+  '聚合', '聚合根', 'aggregate',
+  // 2 限界上下文
+  '限界上下文', 'bounded context',
+  // 3 读写模型
+  '读写模型', 'cqrs', '写模型', '读模型',
+  // 4 API（精确短语，避免裸 api 假阳性）
+  'api 签名', 'api 端点', 'api 变更', 'api 新增', '新增 api', 'api 契约', 'endpoint', '端点',
+  // 5 DB schema（精确短语，避免裸 schema 误命中测试矩阵术语）
+  'db schema', '数据库 schema', '表结构', 'ddl', '数据库表', '索引变更',
+  // 配置契约 key
+  'filter.args',
+];
+
+/**
+ * 否定上下文（行级）：否定词可能出现在关键词**之后**同句（如"范围外…`filter.args` …一律不动"）。
+ * 宽松匹配是刻意的——误判为 negated 只会让门走完整路径（安全），
+ * 误判为 positive 才会放行 fast path（危险）。
+ */
+const LINE_NEGATION_RE = /(不动|不涉及|不变更|不新增|不修改|不改变|不调整|不包含|严禁|不得|禁止|零变更|无变更|无新增|无修改|保持不变|unchanged|no change|without)/i;
+const NEGATION_ADJACENT_RE = /(不|无|非|未|零|no|not)\s*$/;
+
+/**
+ * 变更语境：关键词前文出现变更动词才计为**正向**信号。
+ * 仅"提到"关键词（如"按 filter.args 断言写回"）属中性，不构成架构变更信号。
+ */
+const CHANGE_VERB_RE = /(新增|修改|变更|调整|增加|删除|引入|扩展|重构|改造|迁移|升级|add|new|modify|change|update|refactor|migrate)/i;
+
+const PRESENTATION_EXTS = new Set(['.vue', '.jsx', '.tsx', '.less', '.css', '.scss', '.sass', '.html']);
+const BACKEND_EXTS = new Set(['.java', '.go', '.py', '.rb', '.rs', '.kt', '.kts', '.cs']);
+const CONFIG_EXTS = new Set(['.yaml', '.yml', '.json', '.sql', '.toml', '.ini', '.properties']);
+const SCRIPT_EXTS = new Set(['.js', '.ts', '.mjs', '.cjs', '.mts', '.cts']);
+const TEST_PATTERNS = [
+  /\.spec\.[cm]?[jt]sx?$/i,
+  /\.test\.[cm]?[jt]sx?$/i,
+  /Tests?\.java$/,
+  /_test\.go$/i,
+  /^test_.*\.py$/i,
+  /Tests?\.(kt|cs)$/,
+];
+
+const CODE_EXT_PATTERN = [...PRESENTATION_EXTS, ...BACKEND_EXTS, ...CONFIG_EXTS, ...SCRIPT_EXTS]
+  .map(e => e.slice(1))
+  .sort((a, b) => b.length - a.length)
+  .join('|');
+
+const FILE_RE = new RegExp(`(?:[\\w.-]+/)*[\\w.-]+\\.(?:${CODE_EXT_PATTERN})(?![\\w])`, 'gi');
+
+function classifyFile(file) {
+  const ext = path.extname(file).toLowerCase();
+  const base = path.basename(file);
+  if (TEST_PATTERNS.some(re => re.test(base))) return 'test';
+  if (PRESENTATION_EXTS.has(ext)) return 'presentation';
+  if (BACKEND_EXTS.has(ext)) return 'backend';
+  if (CONFIG_EXTS.has(ext)) return 'config';
+  if (SCRIPT_EXTS.has(ext)) return 'script';
+  return 'other';
+}
+
+/** 文件提取：剔除 node_modules 引用，同名文件保留最完整路径。 */
+function extractFiles(text) {
+  const byBase = new Map();
+  for (const m of text.matchAll(FILE_RE)) {
+    const f = m[0];
+    if (/(^|\/)node_modules\//.test(f)) continue;
+    const base = path.basename(f);
+    const prev = byBase.get(base);
+    if (!prev || f.length > prev.length) byBase.set(base, f);
+  }
+  return [...byBase.values()];
+}
+
+/** 关键词逐次出现的语境统计：negated（否定）/ positive（变更动词）/ neutral（仅提及）。 */
+function findKeyword(text, keyword) {
+  const kw = keyword.toLowerCase();
+  const stat = { occurrences: 0, positive: 0, negated: 0, neutral: 0 };
+  for (const line of text.split('\n')) {
+    const lowerLine = line.toLowerCase();
+    let idx = lowerLine.indexOf(kw);
+    while (idx !== -1) {
+      stat.occurrences += 1;
+      const before = line.slice(Math.max(0, idx - 30), idx);
+      if (LINE_NEGATION_RE.test(line) || NEGATION_ADJACENT_RE.test(before)) stat.negated += 1;
+      else if (CHANGE_VERB_RE.test(before)) stat.positive += 1;
+      else stat.neutral += 1;
+      idx = lowerLine.indexOf(kw, idx + kw.length);
+    }
+  }
+  return stat;
+}
+
+/**
+ * 扫描 change 的规划制品，返回架构信号证据。
+ * @returns {{ signal: 'none'|'weak'|'strong', hits: object, evidence: string[], sources: string[] }}
+ */
+export function collectArchSignals(changeDir) {
+  const sources = [];
+  for (const name of ['change-brief.md', 'execution-contract.md']) {
+    const p = path.join(changeDir, name);
+    if (fs.existsSync(p)) sources.push({ name, text: fs.readFileSync(p, 'utf-8') });
+  }
+
+  const text = sources.map(s => s.text).join('\n');
+
+  const keywords = [];
+  const negated = [];
+  const neutral = [];
+  for (const kw of ARCH_KEYWORDS) {
+    const stat = findKeyword(text, kw);
+    if (stat.occurrences === 0) continue;
+    if (stat.positive > 0) keywords.push(kw);
+    else if (stat.negated > 0) negated.push(kw);
+    else neutral.push(kw);
+  }
+
+  const files = { presentation: [], backend: [], config: [], script: [], test: [], other: [] };
+  for (const f of extractFiles(text)) files[classifyFile(f)].push(f);
+
+  const hasSql = files.config.some(f => f.toLowerCase().endsWith('.sql'));
+
+  let signal;
+  if (keywords.length > 0) signal = 'strong';
+  else if (files.backend.length > 0 || hasSql) signal = 'weak';
+  else if (files.presentation.length > 0) signal = 'none';
+  else signal = 'weak';
+
+  const evidence = [];
+  if (sources.length === 0) {
+    evidence.push('no change-brief.md / execution-contract.md found — signal defaults to weak');
+  }
+  evidence.push(keywords.length === 0
+    ? 'no architecture keyword in change context'
+    : `architecture keyword in change context: ${keywords.join(', ')}`);
+  if (negated.length > 0) evidence.push(`negated (not a signal): ${negated.join(', ')}`);
+  if (neutral.length > 0) evidence.push(`mentioned without change context (not a signal): ${neutral.join(', ')}`);
+  evidence.push(
+    `code files — presentation=${files.presentation.length}, backend=${files.backend.length}, `
+    + `config=${files.config.length}, script=${files.script.length}, test=${files.test.length}`,
+  );
+  if (signal === 'none') {
+    evidence.push('all evidence points to presentation-layer only — fast-path candidate (sub-agent must still confirm)');
+  }
+
+  return {
+    signal,
+    hits: { keywords, negatedKeywords: negated, neutralKeywords: neutral, files },
+    evidence,
+    sources: sources.map(s => s.name),
+  };
+}
+
+export async function run(positionals, values) {
+  const changeDirArg = positionals[0];
+  if (!changeDirArg) {
+    console.error('Usage: tf arch precheck <change-dir> [--json]');
+    process.exit(2);
+  }
+  const changeDir = path.resolve(changeDirArg);
+  const result = collectArchSignals(changeDir);
+
+  if (values.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`arch precheck — signal: ${result.signal}`);
+    console.log(`  sources: ${result.sources.join(', ') || '(none)'}`);
+    for (const line of result.evidence) console.log(`  - ${line}`);
+    console.log('  note: evidence only — the architecture-design sub-agent still makes the decision.');
+  }
+  // 证据工具：恒以 0 退出，不阻断流程。
+  process.exit(0);
+}

package/scripts/lib/cmd-arch.mjs

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
+import * as archPrecheck from './arch-precheck.mjs';
 
 const ARCH_STATE_FILE = '.team-flow/arch-state.json';
 
@@ -16,6 +17,7 @@ export async function run(args) {
       'project-root': { type: 'string' },
       mode: { type: 'string', default: 'reconstruction' },
       'baseline-ref': { type: 'string', default: 'prd/vN/' },
+      json: { type: 'boolean', default: false },
     },
     allowPositionals: true,
   });
@@ -23,7 +25,9 @@ export async function run(args) {
   const sub = positionals[0];
   if (sub === 'init') return init(values);
   if (sub === 'show') return show(values);
-  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show');
+  // v0.22 §88.3.2：架构门判据的确定性证据工具（证据 only，退出码恒 0）
+  if (sub === 'precheck') return archPrecheck.run(positionals.slice(1), values);
+  console.error('Usage: tf arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>] | tf arch show | tf arch precheck <change-dir> [--json]');
   process.exit(2);
 }
 

package/scripts/lib/cmd-doctor.mjs

@@ -5,6 +5,8 @@ import { loadConfig } from './config-loader.mjs';
 import { PLATFORM_RUNTIME_INVENTORY } from './platform-runtime-inventory.mjs';
 // 非法 state 巡检所需的共享常量与读取器(来源:workflow-feedback 2026-08-01,#100004)。
 import { readState, VALID_STATES } from './state-loader.mjs';
+// v0.22 §85：tasks_skipped 豁免判定复用 guard 侧唯一真相源，避免同一规则两处实现漂移。
+import { hasExplicitTasksSkip } from '../guard/checks/tasks-gate-exemptions.mjs';
 
 const RUNTIME_SKILLS = new Set([
   'workflow-start', 'need-explorer', 'spec-writer', 'contract-builder',
@@ -258,8 +260,8 @@ function checkChangeStates(root) {
   return { pass: true, message: `${checked} change(s) have legal state values` };
 }
 
-// v0.13 §52 B4 测试门禁卫生巡检（C1-domain-policy 事件修复）：
-// 1. test_matrix_skipped=true 必须附 test_matrix_skip_reason（可审计豁免）；
+// v0.13 §52 B4 测试门禁卫生巡检（C1-domain-policy 事件修复）；v0.22 §85 扩展 tasks_skipped：
+// 1. test_matrix_skipped / tasks_skipped = true 必须附对应 reason（可审计豁免）；
 // 2. 状态引用的产物文件必须存在（arch_review_report / test_evidence_path）——
 //    C1 现场曾出现 arch_review_report 指向不存在的 auto-review.md。
 // DP 时间戳顺序检查评估后未纳入：closing 后的 DP-7 时间戳晚于 last_transition 属合法，
@@ -283,6 +285,11 @@ function checkChangeTestGates(root) {
       && !(typeof state.test_matrix_skip_reason === 'string' && state.test_matrix_skip_reason.trim())) {
       issues.push(`${d}: test_matrix_skipped=true without test_matrix_skip_reason`);
     }
+    // v0.22 §85：tasks_skipped 沿用同一可审计豁免范式（跳过必须附理由），
+    // 判定复用 tasks-gate-exemptions 的共享谓词（与 guard 同一真相源）。
+    if (state.tasks_skipped === 'true' && !hasExplicitTasksSkip(state)) {
+      issues.push(`${d}: tasks_skipped=true without tasks_skip_reason`);
+    }
     for (const field of ['arch_review_report', 'test_evidence_path']) {
       const ref = state[field];
       if (typeof ref === 'string' && ref.trim() && !existsSync(join(changeDir, ref))) {

package/scripts/lib/cmd-state.mjs

@@ -38,6 +38,8 @@ const SETTABLE_FIELDS = [
   'compound_skipped',
   // Test matrix gate (v0.12 §45.4 + v0.13 §48.2)
   'test_matrix_skipped', 'test_matrix_skip_reason',
+  // Tasks gate (v0.22 §85：hotfix/tweak 显式跳过 tasks.md，须附理由)
+  'tasks_skipped', 'tasks_skip_reason',
 ];
 
 export async function run(args) {

package/scripts/lib/state-loader.mjs

@@ -74,6 +74,9 @@ const BUILTIN_DEFAULTS = {
   test_matrix_skip_reason: null,
   // Test evidence (v0.13 §50：tf test record 落盘的 runner 输出证据路径)
   test_evidence_path: null,
+  // Tasks gate (v0.22 §85：hotfix/tweak 跳过 spec-writer 时显式跳过 tasks.md)
+  tasks_skipped: null,
+  tasks_skip_reason: null,
   // 注意：schema_version 故意不在 BUILTIN_DEFAULTS 中（v0.13 §48.1）——
   // 它只由 `tf state init` 在 change 创建时打戳，字段缺失本身就是"存量 change"信号。
 };
@@ -196,6 +199,10 @@ export function writeState(changeDir, state) {
   lines.push('');
   lines.push('# === Test evidence (v0.13 §50) ===');
   lines.push(`test_evidence_path: ${state.test_evidence_path ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Tasks gate (v0.22 §85) ===');
+  lines.push(`tasks_skipped: ${state.tasks_skipped ?? 'null'}`);
+  lines.push(`tasks_skip_reason: ${state.tasks_skip_reason ?? 'null'}`);
 
   fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
 }

package/scripts/lint/rules/behavior-consistency.mjs

@@ -25,7 +25,9 @@ export default {
 
     // Check 2: "route to" consistency with workflow-start
     if (skillName !== 'workflow-start') {
-      const routeRefs = [...content.matchAll(/[Rr]oute to [`""]?([a-z-]+)[`""]?/g)];
+      // v0.22 §90：加 `(?![a-z\/-])` 排除路径式目标——原正则把 "route to `references/xxx.md`"
+      // 捕获为 skill 名 "references"，产生 error 级误报（ce-plan SKILL.md:64）。
+      const routeRefs = [...content.matchAll(/[Rr]oute to [`""]?([a-z-]+)[`""]?(?![a-z\/-])/g)];
       for (const [, target] of routeRefs) {
         // This skill says "route to X" — workflow-start should have a corresponding rule
         // We flag this for manual verification (can't easily cross-check without loading workflow-start)

package/scripts/team-flow.mjs

@@ -67,6 +67,8 @@ Commands:
   arch init [--mode reconstruction|design] [--baseline-ref <prd/vN/>]
                         Stamp project-level arch_baseline into .team-flow/arch-state.json (v0.35.0 §59.4)
   arch show             Show current project architecture baseline state
+  arch precheck <change-dir> [--json]
+                        Emit deterministic architecture-gate evidence (v0.22 §88; evidence only, exit 0)
   arch-merge <change-dir> [--project-root <path>] [--dry-run]
                         Merge architecture delta into global docs/architecture/
   test-merge <change-dir> [--project-root <path>] [--dry-run]
@@ -81,6 +83,9 @@ Commands:
                         Detect project layout (single/monorepo/multi-repo) + code repos, write repo_layout config (v1.0 §3)
   test record <dir> --from <runner-output> [--runner auto|maven-surefire|jest|pytest]
                         Record programmatic test evidence (v0.13 §50; feeds tests-passing gate)
+                        jest requires --json output (e.g. npx jest --json --outputFile=<path>);
+                        maven-surefire: console summary or surefire XML dir/file;
+                        pytest: terminal summary or junit XML (--junitxml)
   config [options]      Display or modify configuration
   config --resolve-model <profile>  Resolve a configured model profile without switching models
   state <sub> <dir>     Manage .team-flow.yaml state (init|check|transition|get|rebuild)
@@ -109,7 +114,9 @@ Commands:
   execution revise <change-dir> --mode sdd --confirm --reason <text> --wave <id>:<strategy>:<task,...> [--acknowledge-recommendation]
                         Upgrade inline/batch to SDD, or replan existing SDD waves, as a new revision
   execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict pass|fail
-                        Record one review receipt for a planned wave
+                        Record one review receipt for a planned wave.
+                        --report must resolve inside <change-dir>/.superpowers/sdd/reviews/
+                        (the change review overlay; other paths are rejected)
   deisolate <change-dir> [--merge] [--force] [--clean] [--json]
                         Show worktree status / merge branch back / clean worktree
   runtime check-update  Run a portable update check for canonical skills

package/skills/architecture-design/SKILL.md

@@ -67,7 +67,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 
 - `change-brief.md`（scope / AC / 技术方向）
 - `requirement/vN/plan.md` 高阶技术设计段（模块边界/技术选型/数据流/关键聚合划分）
-- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的唯一事实源
+- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的唯一事实源；**Fast Path 下不读**（见 `### Fast Path`）
 - 全局 `docs/architecture/`（As-Is 实际态基线，已落地部分）
 - 现有 `specs/`（若有）
 
@@ -81,6 +81,20 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 4. **API 变更**：是否涉及 API 新增/变更（端点、方法签名、请求响应 schema）
 5. **DB schema 变更**：是否涉及数据库表结构、字段、索引变更
 
+### Fast Path：precheck 证据驱动（v0.22 §88.3.2）
+
+> **术语区分**：本节的 Fast Path 专指**架构判断门的快路径**，与 workflow-start 的 Fast-Path Routing（hotfix/tweak 路由）无关。
+> **优先级**：本节条件优先于下文「执行流程」与「上下文加载协议」——Fast Path 命中时，那两节的架构文件读取要求一律不适用。
+
+**先跑证据工具**：`tf arch precheck <change-dir> --json` —— 输出确定性证据（架构关键词的**变更语境**命中 / 否定命中 / 仅提及；改动文件按表现层/后端/配置/脚本/测试分类）。**正常调用退出码恒 0（缺参数属用法错误 exit 2），它是证据不是判断**。
+
+| precheck 输出 | 路径 | 行为 |
+|---|---|---|
+| `signal: none`（无正向架构关键词 ∧ 无后端文件 ∧ 无 `.sql` ∧ 有表现层文件） | **Fast Path** | 只读 `change-brief.md` + precheck 输出；本路径**不读 `docs/architecture/` 下任何文件（含 `INDEX.md`）**；执行五项检查后返回 `skipped`，reason 引用 precheck 证据 |
+| `signal: weak` / `strong` | 完整路径 | 现状（读快照 + 全局基线 + 完整五项检查） |
+
+**红线**：Fast Path 下若发现 precheck 证据与 brief 不符（如 brief 明确提到新增聚合但 precheck 未命中），**必须回退完整路径**——判断权始终在本子代理，precheck 只用于缩小输入范围。
+
 ### 路由分流（v0.35.0 新增）
 
 当产品级架构快照存在时（已建档项目），判定结果再按"产品级决策 vs change 内实现细节"分流：
@@ -103,7 +117,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 ### 执行流程
 
 ```
-1. 读取输入（brief + plan + specs + 全局 ARCHITECTURE.md）
+1. 读取输入（brief + plan + specs + 全局 ARCHITECTURE.md）——**Fast Path 裁剪为「brief + precheck 输出」**
 2. 执行五项检查
 3. 全部为否：
    → decision: skipped
@@ -196,7 +210,7 @@ architecture-design 执行时的上下文组装：
 1. 执行 `tf solutions inject --phase architecture`（失败静默）——注入 `docs/solutions/` 中 phase=architecture 的历史架构决策经验（BC 边界取舍/聚合划分理由/事件投影设计踩坑）
 2. 读取失败 / 无条目 → 静默跳过，不阻断（advisory 级，与 S1 复利注入同语义）
 
-**始终加载**：
+**始终加载**（**Fast Path 除外**——见上文 `### Fast Path`，该路径不读 `docs/architecture/` 下任何文件）：
 1. `Read docs/architecture/INDEX.md`（~50行摘要）
 2. `Read changes/<name>/change-brief.md`（如有）
 3. `Read changes/<name>/proposal.md`（如有）

package/skills/build-executor/SKILL.md

@@ -142,9 +142,9 @@ For full/hotfix by default. Execute waves as dispatched by workflow-start.
 
 每个 wave 完成、通知 workflow-start 审查前，验证测试**实际执行**的数量（设计增强方案 v0.18 §76，来源：workflow-feedback 2026-08-06——64% 测试静默跳过但报告全绿）：
 
-1. 运行测试套件后，用 `tf test record <change-dir> --from <runner-output-file>` 解析**实际执行数量**（`Tests run: N`）。
+1. 运行测试套件后，用 `tf test record <change-dir> --from <runner-output-file>` 解析**实际执行数量**。**证据文件的产出形态随 runner 而异（v0.22 §86）**：jest 必须 `--json`（如 `npx jest --json --outputFile=<path>`；控制台汇总行 `Tests: N passed` 不被解析）；maven-surefire 用控制台汇总行（`Tests run: N`）或 surefire XML 目录/文件；pytest 用 terminal summary 或 junit XML（`--junitxml=<path>`）。解析规则以 `scripts/lib/test-record.mjs` 为准（新增 runner 需先在该处注册）。
 2. 对照 test-matrix 当前 wave 覆盖的用例数（**分母排除 `test_tier=e2e`**——E2E case 由 Playwright 执行，不进入 `mvn test`/`npm test` 的 `Tests run: N`，口径与 code-reviewer Step 5b / release-archivist Step 2b 一致）：实际执行数明显低于预期（< 70%）→ **警告 + 调查**（@Nested 静默跳过、测试未被发现、编译期跳过等），未查明前不得报告 "N tests pass"。
-3. 报告引用实际执行数（`Tests run: N`），而非 BUILD SUCCESS 或编译通过数量。
+3. 报告引用实际执行数（按 runner 的计数口径），而非 BUILD SUCCESS 或编译通过数量。
 
 ### Per-Task Loop
 1. **Dispatch implementer**: Load the template with `tf runtime asset read skills/build-executor/implementer-prompt.md`. Extract task brief with `scripts/task-brief PLAN_FILE N`. Include: where task fits, brief path, interfaces from prior tasks, report file path.

package/skills/build-executor/references/execution-modes.md

@@ -35,7 +35,7 @@ Dispatch according to the persisted plan, review each planned wave, and run a fi
 1. Read the current plan with `tf execution show <change-dir> --json`; only waves with `current: true` and `eligible: true` may start.
 2. A `parallel` wave may dispatch independent tasks simultaneously only when the platform supports concurrent dispatch.
 3. A `serial` wave dispatches one task at a time in listed order.
-4. After every wave, write a review report, then record one receipt:
+4. After every wave, write a review report **inside the change review overlay** `<change-dir>/.superpowers/sdd/reviews/` (v0.22 §86: other paths are rejected; the overlay is auto-created), then record one receipt:
    ```bash
    tf execution review <change-dir> \
      --wave <wave-id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>

package/skills/build-executor/task-reviewer-prompt.md

@@ -141,9 +141,10 @@ Subagent (general-purpose):
     ## Output Format
 
     Write your full review to [REVIEW_REPORT_FILE]. This distinct review report
-    path must point to a non-empty, persisted review report before the
-    controller records a receipt. After the verdict, provide the exact receipt
-    command for the controller:
+    path must resolve inside `<change-dir>/.superpowers/sdd/reviews/` and point
+    to a non-empty, persisted review report before the controller records a
+    receipt. After the verdict, provide the exact receipt command for the
+    controller:
 
     ```bash
     tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
@@ -184,7 +185,7 @@ Subagent (general-purpose):
 - `[BRIEF_FILE]` — REQUIRED: the task brief file (`scripts/task-brief PLAN N` prints the path; same file the implementer worked from)
 - `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from the plan's Global Constraints section or the spec: exact values, formats, and stated relationships between components (not process rules — those are already in this template)
 - `[IMPLEMENTER_REPORT_FILE]` — REQUIRED: the file the implementer wrote its detailed report to
-- `[REVIEW_REPORT_FILE]` — REQUIRED: a distinct, persisted, non-empty file where the reviewer writes this review; this exact path is stored in the receipt
+- `[REVIEW_REPORT_FILE]` — REQUIRED: a distinct, persisted, non-empty file under `<change-dir>/.superpowers/sdd/reviews/` (the overlay) where the reviewer writes this review; this exact path is stored in the receipt
 - `[BASE_SHA]` — commit before this task
 - `[HEAD_SHA]` — current commit
 - `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review package to (`scripts/review-package BASE HEAD` prints the unique path it wrote; the package never enters the controller's context)

package/skills/code-reviewer/SKILL.md

@@ -16,7 +16,7 @@ Two responsibilities: requesting review (dispatching a reviewer subagent) and re
 1. Get SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
 2. Dispatch `general-purpose` subagent using template at `skills/code-reviewer/code-reviewer-prompt.md`
 3. Fill placeholders: `[DESCRIPTION]` (what was built), `[PLAN_OR_REQUIREMENTS]` (contract/spec reference), `[BASE_SHA]`, `[HEAD_SHA]`, `[WAVE_ID]`, and a distinct `[REVIEW_REPORT_FILE]`.
-4. Require the reviewer to write a non-empty persisted review report at `[REVIEW_REPORT_FILE]`, then record that exact path in the wave receipt: `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>`.
+4. Require the reviewer to write a non-empty persisted review report at `[REVIEW_REPORT_FILE]` — **inside the change review overlay** `<change-dir>/.superpowers/sdd/reviews/` (v0.22 §86: other paths are rejected by the CLI; the overlay directory is auto-created). Then record that exact path in the wave receipt: `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>`.
 5. Act on feedback: Critical/Important findings require a `fail` receipt, focused repair, re-review, and replacement `pass` receipt before a dependent wave or closing can proceed. Note Minor for later, push back with reasoning if reviewer is wrong.
 
 ### Minimality And Scope

package/skills/code-reviewer/code-reviewer-prompt.md

@@ -105,9 +105,10 @@ Subagent (general-purpose):
     ## Output Format
 
     Write your full verdict to [REVIEW_REPORT_FILE]. This review report path
-    must point to a non-empty, persisted review report before the controller
-    records a receipt. Include the wave ID, base SHA, head SHA, and that review
-    report path. End with the exact receipt command:
+    must resolve inside `<change-dir>/.superpowers/sdd/reviews/` and point to a
+    non-empty, persisted review report before the controller records a receipt.
+    Include the wave ID, base SHA, head SHA, and that review report path. End
+    with the exact receipt command:
 
     ```bash
     tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
@@ -169,7 +170,7 @@ Subagent (general-purpose):
 - `[BASE_SHA]` — starting commit
 - `[HEAD_SHA]` — ending commit
 - `[WAVE_ID]` — planned execution wave under review
-- `[REVIEW_REPORT_FILE]` — REQUIRED: distinct, persisted, non-empty review report path stored in the execution receipt
+- `[REVIEW_REPORT_FILE]` — REQUIRED: distinct, persisted, non-empty review report path under `<change-dir>/.superpowers/sdd/reviews/` (the overlay); stored in the execution receipt
 
 **Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
 

package/skills/contract-builder/SKILL.md

@@ -113,7 +113,13 @@ See `test-matrix.md` for the full test case matrix (附属产物, 独立 hash).
 
 ### Hotfix/Tweak Exemption
 
-hotfix/tweak workflow 不生成 test-matrix.md（guard 豁免）；full workflow 确无自动化测试需求的特例（纯文档/纯配置）同理。设置显式 skip + 理由（v0.13 §48.2 可审计豁免，**不允许静默不生成**）：
+**hotfix/tweak**：不生成 test-matrix.md 与 tasks.md（guard 豁免），设置显式 skip + 理由（v0.13 §48.2 + v0.22 §85 可审计豁免，**不允许静默不生成**）：
+```bash
+tf state set <change-dir> test_matrix_skipped true && tf state set <change-dir> test_matrix_skip_reason "<一句话说明>"
+tf state set <change-dir> tasks_skipped true && tf state set <change-dir> tasks_skip_reason "<一句话说明>"
+```
+
+**full workflow 特例**（纯文档/纯配置，确无自动化测试需求）：**只**豁免测试矩阵，**不得设置 `tasks_skipped`**——`tasks.md` 是 spec-writer 的核心产物，full 路径不允许跳过（v0.22 §85.4）；该禁令**代码层强制**：`tasks-complete` 对 full/auto 置键直接 FAIL。
 ```bash
 tf state set <change-dir> test_matrix_skipped true && tf state set <change-dir> test_matrix_skip_reason "<一句话说明>"
 ```
@@ -137,13 +143,38 @@ Refresh if: scope changed in proposal, requirements changed in specs, constraint
 
 ## Hotfix Mode
 
-Generate minimal contract: Intent Lock (one sentence), Task List (numbered), Approval Gate (DP-3). Skip Scope Fence, Build Rules, Review Gates, Test Evidence. Still requires DP-3 approval.
+**适用判据**（须同时满足；任一条不满足 → 走完整契约）：
+
+1. 改动文件 ≤2
+2. 不新增/变更：API 签名、请求响应 schema、DB schema、`filter.args` 等配置契约 key
+3. 变更性质 = 文案 / 样式 / 布局 / 提示语 / 日志措辞
+
+**轻契约骨架**（目标 ≤60 行；>60 行须在 DP-3 摘要说明理由；>100 行视为不适用轻契约、回退完整契约）：
+
+| 章节 | 内容 |
+|---|---|
+| `## Intent Lock` | 1-2 句（问题 + 范围） |
+| `## 锁定值表` | 改前/改后逐字——防实现偏差的核心，必留 |
+| `## 范围栅栏` | 改动文件 + 禁改项清单 |
+| `## Execution Batch` | 编号任务（含验证任务） |
+| `## Test Matrix` | 测试策略——**代码解析锚点，标题不可删**（除非 `test_matrix_skipped=true`） |
+| `## Approval Gate (DP-3)` | 审批对象声明 |
+
+**移出轻契约**：AC 覆盖矩阵、信息量守恒核对表、DOM 结构详述、金字塔/复杂度分析、人工核验义务（改由 closing 总结承载）；Review Gates 章节不写入契约，但 **wave 级 review receipt 仍须由 build-executor 记录**——closing 的 `execution-reviews-passed` 维度对 hotfix 同样考核（`guard.mjs:75`）。
+
+**其余代码锚点**：涉及 UI 时保留 `## UX 增量`；GLAF4 委托时保留 `## GLAF4 Delegation`。除此之外的段落代码不解析，可自由裁剪；但契约全文入 `contract_hash`，裁剪后须 `tf state rebuild`。
+
+**质量不变量（不得因轻量化削减）**：锁定值逐字、范围栅栏、测试策略、Escalation 条件。
+
+Still requires DP-3 approval.
+
+**非存量 hotfix/tweak 必须设置显式 skip（v0.13 §50 + v0.22 §85）**：hotfix/tweak 不生成矩阵与 `tasks.md`，但 closing 的 `tests-passing` / `tasks-complete` 两个门禁仍考核非存量 change——生成最小契约后立即执行上方 Hotfix/Tweak Exemption 段的四条 `tf state set`，否则 release-archivist 轻量收尾会被门禁阻断（v0.22 §85：修复前 `tasks-complete` 无豁免分支，closing 死锁）。
 
-**非存量 hotfix/tweak 必须设置显式 skip（v0.13 §50）**：hotfix/tweak 不生成矩阵，但 closing 的 tests-passing 门禁仍考核非存量 change——生成最小契约后立即执行 Hotfix/Tweak Exemption 段的两条 `tf state set`（`test_matrix_skipped=true` + 理由），否则 release-archivist 轻量收尾会被门禁阻断。
+**`tasks.md` 归属（v0.22 §85）**：hotfix/tweak 默认跳过（上条），但若该 change 确实需要任务记录，`tasks.md` 由本 skill 一并产出——归属 contract-builder（本 skill 已有 `tasks.md → Execution Batches` 的 Artifact Mapping，反向生成成本最低）；任务文本不再经 spec-writer（hotfix/tweak 已跳过它）。
 
 ## Guardrails
 
-- **状态字段禁写（v0.30.0）**：仅写本 skill 的 `dp_3_*` 决策字段；**MUST NOT** 修改 `state`/`workflow` 核心字段——状态转换由主代理经 `tf state transition` 执行。`tf state init` 只创建状态文件，不改 `state` 值（来源：workflow-feedback 2026-08-01）。
+- **状态字段禁写（v0.30.0；v0.22 §85 澄清写入白名单）**：仅写本 skill 的 `dp_3_*` 决策字段，以及本 skill 职责内的门禁豁免键——`test_matrix_skipped` / `test_matrix_skip_reason`（v0.13 §50）、`tasks_skipped` / `tasks_skip_reason`（v0.22 §85）；**MUST NOT** 修改 `state`/`workflow` 核心字段——状态转换由主代理经 `tf state transition` 执行。`tf state init` 只创建状态文件，不改 `state` 值（来源：workflow-feedback 2026-08-01）。
 
 - Do not continue to implementation if ambiguity remains
 - Do not approve the contract on the user's behalf

package/skills/release-archivist/SKILL.md

@@ -161,7 +161,7 @@ Merge change-level architecture artifacts to the global `docs/architecture/` bas
 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`).
+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.
 
@@ -193,7 +193,7 @@ This merges `test-matrix.md` into `docs/test-ledger/`:
 - **appendChangelog**: archive test-matrix.md → `changelog/{change-id}.md`
 - **rewriteIndex**: recalculate module/case/deferred counts, rewrite `INDEX.md`
 
-Skip silently when `test-matrix.md` does not exist (legacy change or test_matrix_skipped=true).
+Skip silently when `test-matrix.md` does not exist (legacy change or test_matrix_skipped=true) — 前置判据见 `## Lightweight Closure > 回写链前置判据`（v0.22 §87：先判断再决定是否执行命令）。
 
 **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.
 
@@ -266,6 +266,15 @@ 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 正文句）。
+
+| 回写项 | 前置判据 | 不满足时登记 |
+|---|---|---|
+| arch-merge | `test -d <change-dir>/architecture/` | `skipped` |
+| prototype-sync | 契约含 `## UX 增量` 段 | `no UX delta` |
+| test-merge | `test -f <change-dir>/test-matrix.md` | `skipped` |
+| compound promotion | `test -f <change-dir>/learnings.md` | `no learnings` |
+
 **⚠️ tests-passing 门禁不因轻量收尾而豁免（v0.13 §50）**：hotfix/tweak 的 `executing→closing` guard 同样挂 `tests-passing`。非存量 change 仅记 DP-6/DP-7 不足以放行——必须二选一：① `test_matrix_skipped=true` + `test_matrix_skip_reason` 已由 contract-builder 设置（hotfix/tweak 常规路径，先 `tf state get` 核实）；② 有代码变更时补跑测试套件并 `tf test record <change-dir> --from <输出>`。
 
 ## Exception Handling

package/skills/workflow-start/SKILL.md

@@ -87,7 +87,7 @@ Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before
 
 > **⛔ 串行约束（v0.30.0）**：四步严格串行。**修复子代理（architecture-design）完成前 MUST NOT dispatch 审查子代理（architecture-reviewer）**——并行会使审查跑在修复之前、误报"全部未修复"FAIL（来源：workflow-feedback 2026-08-01）。并行白名单：仅多个独立 change 的工作可并行；修复→审查、设计→审查必须串行。
 
-1. **Dispatch**: `architecture-design` as sub-agent（**输入含 `docs/architecture/iterations/<vN>/architecture.md` 产品级架构快照**，v0.36.0——变更级只引用产品级聚合注册表，不重定义）→ returns `decision` + `reason` + `artifacts`。**⛔ 记录子代理 ID**（后续循环修正和 DP-A 调整必须通过此 ID 恢复，禁止启动新子代理）
+1. **Dispatch**: 先跑 `tf arch precheck <change-dir> --json`（v0.22 §88.3.2：确定性证据工具，正常调用退出码恒 0；`signal: none` 时子代理走 Fast Path，只读 brief + precheck 输出）→ dispatch `architecture-design` as sub-agent（**输入含 `docs/architecture/iterations/<vN>/architecture.md` 产品级架构快照**，v0.36.0——变更级只引用产品级聚合注册表，不重定义；**Fast Path 命中时不传快照**）→ returns `decision` + `reason` + `artifacts`。**⛔ 记录子代理 ID**（后续循环修正和 DP-A 调整必须通过此 ID 恢复，禁止启动新子代理）
 2. **Auto-review** (decision=required 时触发): 校验产物文件存在且非空 → dispatch `architecture-reviewer` sub-agent（**记录子代理 ID**，agent 会直接写审查报告到 `changes/<name>/architecture/auto-review.md`）→ FAIL 则通过 **SendMessage 恢复原 architecture-design 子代理**修正（≤3 轮 + 收敛检测，不收敛转人工）
 3. **Reasonableness check + state write**: PASS/PASS_WITH_WARNINGS → write `arch_design_decision` + `arch_review_*` to yaml; skipped + brief 含架构关键词 → BLOCK; required + artifacts 缺失 → BLOCK; required + auto-review FAIL → BLOCK
 4. **DP-A 用户确认门（v0.29.0 §37）**: 输出架构决策摘要 → AskUserQuestion 确认 → 需要调整时**必须通过 SendMessage 恢复原子代理**修改（禁止主代理直接修改，禁止启动新子代理）→ 修改后 SendMessage 恢复原 reviewer 重新 auto-review → 回到本步骤重新确认。含项目规范变更提示（advisory）。详见 `references/routing-rules.md`「Step 4: DP-A」
@@ -132,7 +132,7 @@ Contract exists and approved, contract matches artifacts. Include `DP-4: 执行
 Execution hit blockage: test failure, unexpected behavior, build error, task cannot proceed. After debugging, route back to build-executor.
 
 ### Route to code-reviewer
-The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition.
+The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition. **`--report` 必须落在 change review overlay 内**（`<change-dir>/.superpowers/sdd/reviews/`，v0.22 §86）——其他路径被 CLI 拒绝（`execution-plan.mjs` 的 `validateReviewReportEvidence`）；派发审查子代理时直接给 overlay 路径，避免"任务指令写 `reviews/`、CLI 只认 overlay"导致的双写副本。
 
 **v0.39.0 主动串行编排**：workflow-start 在每个 wave 完成后主动 dispatch code-reviewer，而不是等待 build-executor 完成所有 wave。这是 workflow-start 的编排责任，不是 build-executor 的责任。
 
@@ -167,10 +167,20 @@ work.
 
 ### Fast-Path Routing
 
-**DP-0 处理**（v0.22.5 F03 修复）：hotfix/tweak 路径隐式跳过 DP-0（`dp_0_confirmed` 保持 `null`），因为意图已明确（修复/微调），无需从零探索。contract-builder 的 DP-3 审批成为唯一门禁。
+**DP-0 处理**（v0.22.5 F03；**v0.22 §88 修正**）：hotfix/tweak 路径**仍执行 DP-0**（快速形态：确认 scope / 约束 / AC / 沟通偏好，不重新问"你想做什么"）——实测 H1 的 `dp_0_decisions` 承载了后续契约与实施的全部基线（scope/约束/AC/模式/沟通偏好），隐式跳过会使该信息无处安放；`arch_design_decision == skipped` 时 DP-0 可与 DP-A 合并为一次确认（见下「确认点合并」）。contract-builder 的 DP-3 审批仍是唯一硬门禁。
 
-- **Hotfix**: Route to contract-builder (minimal), skip need-explorer + spec-writer, guard check `exploring bridging --workflow hotfix`, then `bridging -> approved-for-build`, after DP-3 → build-executor (recommend, show, and confirm an execution mode), after → release-archivist (lightweight). Hotfix may skip `proposal.md`, `design.md`, `tasks.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md`, DP-3 approval, and a current execution plan before build. **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门，快速判定是否涉及架构变更（hotfix 可能正是架构缺陷导致）
-- **Tweak**: Route to build-executor (direct edit), skip need-explorer + spec-writer + contract-builder, guard check `exploring approved-for-build --workflow tweak`, after → release-archivist (lightweight). **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门
+**确认点合并（v0.22 §88.3.1）**：为减少用户交互轮次，以下三组可合并为**一次** AskUserQuestion。**门禁强度不变**——`dp_0_confirmed` / `dp_a_result` / `dp_3_result` / `dp_4_result` 仍须写入，guard 维度（`dp3-approved` / `execution-plan-ready`）不豁免：
+
+| 合并组 | 触发条件 | 合并后形态 |
+|---|---|---|
+| DP-0 + DP-A | `arch_design_decision == skipped` | 一次「变更基线确认」：brief 继承 + 架构判定结果 |
+| DP-3 + G4 + DP-4 | 契约已产出且 hash 有效 | 一次「实施授权确认」：批准契约 + 同步选择 + 执行模式 |
+| DP-7 + 代码落地 + G5 | 恒成立 | 一次「归档确认」 |
+
+**不合并**：`arch_design_decision == required` 时 DP-A 必须独立——用户需单独审架构产物。
+
+- **Hotfix**: Route to contract-builder (minimal), skip need-explorer + spec-writer, guard check `exploring bridging --workflow hotfix`, then `bridging -> approved-for-build`, after DP-3 → build-executor (recommend, show, and confirm an execution mode), after → release-archivist (lightweight). Hotfix may skip `proposal.md`, `design.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md`, DP-3 approval, and a current execution plan before build. **`tasks.md` 不得静默缺失（v0.22 §85）**：hotfix 默认不产出该文件，但必须由 contract-builder 显式登记 `tasks_skipped=true` + `tasks_skip_reason`（或一并产出最小任务清单，归属 contract-builder）——`tasks-complete` 在 closing 考核该维度，静默缺失会死锁（修复前即此状态）。**architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门，快速判定是否涉及架构变更（hotfix 可能正是架构缺陷导致）
+- **Tweak**: Route to build-executor (direct edit), skip need-explorer + spec-writer + contract-builder, guard check `exploring approved-for-build --workflow tweak`, after → release-archivist (lightweight). **`tasks.md` 须显式 skip（v0.22 §85）**：tweak 跳过 spec-writer 与 contract-builder，故既无原生 `tasks.md` 也无人代写——由**主代理**经 `tf state set` 写入 `tasks_skipped=true` + `tasks_skip_reason`（`tf state set` 是 CLI 调用，不违反 Artifact Ownership 的 Edit/Write 禁令），否则 `tasks-complete` 在 closing 死锁。tweak 的 `executing:closing` 不含 `test-matrix-complete`（`guard.mjs:82`），矩阵豁免非 guard 必需。**architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门
 
 Post-transition: 💡 `tf inject <change-dir>` to update phase-guard artifacts.
 
@@ -238,7 +248,7 @@ build-executor 修复 findings 后，workflow-start 必须：
 - **No routing to spec-writer without architecture-design gate pass** (v0.9 §26): `arch_design_decision` must be `required` or `skipped` (not `null`). hotfix/tweak 不豁免
 - **No arch state write without auto-review PASS** (v0.28.1 §36): when `decision: required`, auto-review MUST complete with PASS or PASS_WITH_WARNINGS before writing `arch_design_decision` to yaml. FAIL → loop fix (≤3 rounds) or escalate to human
 - **No routing past DP-A without user confirmation** (v0.29.0 §37): architecture-design 四步协议完成后，必须经 DP-A 用户确认门（AskUserQuestion）才能路由到 spec-writer。用户选择"需要调整"时，修改必须通过子代理执行，修改后重新 auto-review + 重新 DP-A 确认
-- **Artifact Ownership — 主代理不得直接修改子代理产物** (v0.29.0 §37): 子代理是其产物的唯一负责人（architecture-design → `architecture/` 目录，spec-writer → `proposal.md`/`specs/`/`design.md`/`tasks.md`，contract-builder → `execution-contract.md`，build-executor → 代码文件）。**tasks.md 的勾选状态属执行期写入区**（v0.49.0 §83.3.4）：任务文本归 spec-writer，勾选标记由 build-executor 在 wave 完成时回写（主代理只检查不代写）。主代理（workflow-start）不得通过 Read + Edit/Write 直接修改子代理的产物文件。修改必须通过 `SendMessage` 恢复原子代理（优先）或启动新子代理执行。**v0.39.0 强化**：主代理 MUST NOT 直接 Edit/Write 任何文件 under `changes/<name>/` 或 `.worktrees/`——无论改动量大小，必须通过 SendMessage 委托子代理执行。例外：仅当子代理无法启动且用户明确授权时，主代理可直接修改，但必须在修改后重新触发对应的 review 验证
+- **Artifact Ownership — 主代理不得直接修改子代理产物** (v0.29.0 §37): 子代理是其产物的唯一负责人（architecture-design → `architecture/` 目录，spec-writer → `proposal.md`/`specs/`/`design.md`/`tasks.md`，contract-builder → `execution-contract.md`，build-executor → 代码文件）。**tasks.md 的勾选状态属执行期写入区**（v0.49.0 §83.3.4）：任务文本归 spec-writer，勾选标记由 build-executor 在 wave 完成时回写（主代理只检查不代写）。**hotfix/tweak 路径的 tasks.md 归属 contract-builder**（v0.22 §85）：该路径跳过 spec-writer，若 change 需要任务记录则由 contract-builder 一并产出；默认路径是显式跳过（`tasks_skipped=true` + `tasks_skip_reason`——hotfix 由 contract-builder 写入，tweak 由主代理写入）。主代理（workflow-start）不得通过 Read + Edit/Write 直接修改子代理的产物文件。修改必须通过 `SendMessage` 恢复原子代理（优先）或启动新子代理执行。**v0.39.0 强化**：主代理 MUST NOT 直接 Edit/Write 任何文件 under `changes/<name>/` 或 `.worktrees/`——无论改动量大小，必须通过 SendMessage 委托子代理执行。例外：仅当子代理无法启动且用户明确授权时，主代理可直接修改，但必须在修改后重新触发对应的 review 验证
 - **修复后必须 re-review** (v0.39.0): build-executor 修复 findings 后，workflow-start 必须 dispatch code-reviewer re-review 确认修复有效，记录 review receipt（verdict=pass）。禁止在 review receipt 未记录或 verdict!=pass 时进入下一阶段
 - **No cross-change artifact modification (v0.30.0)**: 处理 change X 时 **MUST NOT** 编辑 `changes/Y/`（Y≠X）下任何产物。发现跨 change 依赖/问题时：① 在 change X 的 ADR/proposal 中显式声明依赖；② change Y 进入 workflow-start 时，扫描是否有其他 change 声明了对 Y 的依赖并提醒用户；③ change Y 的产物修改必须走 Y 自己的完整流程（architecture-design → auto-review → DP-A），不得绕过。跨 change 一致性核查可调度 `cross-change-consistency-checker` agent（来源：workflow-feedback 2026-08-01）
 
@@ -255,7 +265,8 @@ workflow-start 负责写入以下字段到 `.team-flow.yaml`：
 - `dp_1_*`：need-explorer 完成后的需求澄清决策
 - `dp_2_*`：spec-writer 完成后的规格决策
 - `dp_3_*`：contract-builder 完成后的契约决策
-- `dp_5_*`：build-executor 执行决策 / bug-investigator 调试决策（共享 dp_5；dp_4 预留未用）
+- `dp_4_*`：执行模式选择（由 `tf execution plan --confirm` 程序化写入，不在 SETTABLE_FIELDS；`execution-plan-ready` 维度校验其指向当前 plan revision）
+- `dp_5_*`：build-executor 执行决策 / bug-investigator 调试决策
 - `dp_6_*`：release-archivist 完成后的验证决策
 - `dp_7_*`：release-archivist 归档确认决策
 

package/skills/workflow-start/references/routing-rules.md

@@ -13,6 +13,8 @@ Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before
 
 ### Step 1: Dispatch architecture-design sub-agent
 
+**先跑证据工具（v0.22 §88.3.2）**：`tf arch precheck <change-dir> --json` —— 输出确定性证据（架构关键词的变更语境命中 / 否定命中 / 仅提及 + 改动文件分类），退出码恒 0。`signal: none` → 子代理走 Fast Path（只读 brief + precheck 输出，不读全量 `docs/architecture/`）；`weak` / `strong` → 完整路径。判断权在子代理，precheck 只用于缩小输入范围。
+
 Dispatch `architecture-design` as sub-agent with inputs:
 - `change-brief.md`（scope / AC / 技术方向）
 - `requirement/vN/plan.md` 高阶技术设计段
@@ -228,7 +230,7 @@ Guard: `... check <dir> approved-for-build executing --json` → fail = BLOCK.
 Execution hit blockage: test failure, unexpected behavior, build error. After debugging, route back to build-executor.
 
 ## Route to code-reviewer
-Current planned wave implemented and ready for review. Reviewer must write:
+Current planned wave implemented and ready for review. Reviewer must write the report **inside the change review overlay** `<change-dir>/.superpowers/sdd/reviews/` (v0.22 §86: other paths are rejected by the CLI), then record:
 ```bash
 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>
 ```