@xulthekl/team-flow 0.29.2 → 0.31.0

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

@@ -1,3 +1,3 @@
-# team-flow v0.29.2 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.31.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "description": "Unified workflow plugin: team-flow + compound-engineering core subset + architecture-design + prototype + workflow-orchestrator + workflow-bootstrap + e2e + session-handoff + workflow-feedback. 23 skills + 8 agents, one install.",
+  "description": "Unified workflow plugin: team-flow + compound-engineering core subset + architecture-design + prototype + workflow-orchestrator + workflow-bootstrap + e2e + session-handoff + workflow-feedback. 23 skills + 15 agents, one install.",
   "owner": {
     "name": "LT",
     "url": "https://github.com/LT"
@@ -8,8 +8,8 @@
   "plugins": [
     {
       "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. 23 skills + 8 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.29.2",
+      "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback. 23 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
+      "version": "0.31.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-flow",
-  "version": "0.29.2",
-  "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). 23 skills + 8 agents, one install.",
+  "version": "0.31.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). 24 skills + 15 agents, one install.",
   "source": "./",
   "author": {
     "name": "LT",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.29.2",
+  "version": "0.31.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.29.2"
+    "version": "0.31.0"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "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). 23 skills + 8 agents, one install.",
-  "version": "0.29.2",
+  "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). 23 skills + 15 agents, one install.",
+  "version": "0.31.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.29.2"
+    "version": "0.31.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, and local HTML prototyping.",
-      "version": "0.29.2",
+      "version": "0.31.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md · team-flow
 
-> team-flow 统一插件 = **team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 Playwright E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同（23 skills + 10 agents），支持 9 安装面（Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, Trae, ima-copilot）。
+> team-flow 统一插件 = **team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 Playwright E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同（23 skills + 15 agents），支持 9 安装面（Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, Trae, ima-copilot）。
 
 ## What This Is
 
@@ -12,7 +12,7 @@
 
 ### 身份与依赖关系
 
-- **team-flow**（本插件）：Claude Code / Cursor 等宿主的插件实体（`plugin.json` name = `team-flow`），包含 23 个 skills + 10 个 agents + hooks + templates
+- **team-flow**（本插件）：Claude Code / Cursor 等宿主的插件实体（`plugin.json` name = `team-flow`），包含 23 个 skills + 15 个 agents + hooks + templates
 - **@xulthekl/team-flow**（npm 底座包）：team-flow 的 CLI 工具层（`package.json` name = `@xulthekl/team-flow`，bin = `tf` / `team-flow`），提供状态机、校验、复利 CLI 等运行时能力
 - 关系：team-flow 插件 **包含** @xulthekl/team-flow npm 包作为底座（同一仓库、同一版本）。skills 中的 `tf ...` 调用的是已全局安装的 @xulthekl/team-flow CLI，版本由 session-start hook 自动同步
 - 历史身份（已废弃）：`spec-superflow`（npm 包名，0.11.0 后停止发布）/ `ssf`（CLI 前缀）/ `.spec-superflow.yaml`（状态文件）—— 详见设计增强方案 v0.9 §27
@@ -164,7 +164,7 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
   全局作为下一 change / 下一 PRD 版本的 grounding → 闭环
 ```
 
-## Skills 索引（23 个）
+## Skills 索引（24 个）
 
 | Skill | 归属 | 用途 |
 |---|---|---|
@@ -173,6 +173,7 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 | spec-writer | team-flow | 写 spec |
 | contract-builder | team-flow | 构建执行契约 |
 | build-executor | team-flow | TDD 实现 |
+| test-strategy | team-flow | 测试设计方法论（design_method 三级分层 + 对抗验证 + 复杂度分级，v0.12 §41） |
 | code-reviewer | team-flow | 代码审查 |
 | spec-merger | team-flow | 合并 delta spec |
 | release-archivist | team-flow | 发布归档 |
@@ -207,7 +208,7 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 
 > **规则**：新增 skill 时必须在此表登记所属层级。产品级新需求触发词归 workflow-orchestrator 独占。
 
-### Agents 索引（v0.7 新增，v0.15.0 增至 10 个）
+### Agents 索引（v0.7 新增，v0.30.0 增至 15 个）
 
 | Agent | 职责 | Tools | 触发场景 |
 |-------|------|-------|---------|
@@ -221,6 +222,11 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 | prototype-builder | 原型绘制执行者（种子优先：template.html+layouts.md 组合；**v0.20.0 产物落盘硬闸门**：index.html 未落盘非空禁返 done + 大产出分片；**v0.21.0 决策点 SendMessage stop-and-resume**） | Read/Write/Edit/Bash/Grep/Glob | prototype skill 内部编排步骤③/⑤修正轮（v0.15.0，v0.18.0 种子优先） |
 | prototype-env-scout | 原型环境探查 + 2-3 差异化方向（direction-picker；**v0.20.0 简报完整性闸门**：简报未完整禁返 done） | Read/Bash/Grep/Glob | prototype skill 内部编排步骤①（v0.15.0，v0.18.0 direction-picker） |
 | prototype-reviewer | PRD 6 维度 + P0 grep + craft 4 席 rubric 评审 | Read/Bash/Grep/Glob | orchestrator S2 原型循环每轮产出后 |
+| need-explorer | 需求探索 agent——交互式澄清意图/scope/约束/成功标准，稳定 change 定义、守 DP-1 门（只读型，不产出制品不写代码；workflow-start 路由后、spec-writer 前） | Read/Bash/Grep/Glob | workflow-start 路由，主进程交互式澄清 |
+| spec-writer | 规格编写 agent——产出并打磨 proposal.md / specs/ / design.md / tasks.md 四件规划制品（可写型，规划制品唯一所有者；need-explorer DP-1 后、contract-builder 前） | Read/Bash/Grep/Glob/Write/Edit | workflow-start 路由时作为子代理 dispatch |
+| contract-builder | 执行契约 agent——将规划制品压缩为单一执行握手 execution-contract.md、守 DP-3 批准门（可写型，契约文件唯一所有者；spec-writer DP-2 后、build-executor 前） | Read/Bash/Grep/Glob/Write/Edit | workflow-start 路由时作为子代理 dispatch |
+| build-executor | 构建执行 agent——以契约为权威驱动 TDD 批次实施（SDD/Inline/Batch Inline）、守 TDD Iron Law（可写型，实施代码所有者；契约 DP-3 批准后、release-archivist 前） | Read/Bash/Grep/Glob/Write/Edit | workflow-start 路由时作为子代理 dispatch |
+| release-archivist | 发布归档 agent——执行验证、产出 closing 总结、完成归档就绪（arch-merge → prototype-sync → 复利晋升）（可写型，归档制品所有者；build-executor 后、change 关闭前） | Read/Bash/Grep/Glob/Write/Edit | workflow-start 路由时作为子代理 dispatch |
 
 ## 复利贯穿机制（v0.5 新增）
 

package/CHANGELOG.md

@@ -6,6 +6,94 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-08-01
+
+### Added（设计增强方案 v0.12 §40-§46 测试矩阵驱动开发 + 测试复利闭环）
+
+#### test-strategy skill（24→25 skills）
+- **skills/test-strategy/**：新建测试设计方法论 skill（≤50 行硬规则），含 3 个 references：design-methods-detail.md（10+1 种 design_method 详细说明）、complexity-grading.md（复杂度分级规则 + 圈复杂度计算）、adversarial-patterns.md（对抗验证三招 + 攻击向量模板）
+- **agents/build-executor.md**：frontmatter `skills` 新增 `test-strategy` 预加载
+
+#### test-matrix.md 附属产物
+- **skills/contract-builder/SKILL.md**：新增 Test Matrix Generation 段（12 列格式 + 候选覆盖台账 + 对抗验证段 + GLAF4 Java 路由）
+- **skills/spec-writer/SKILL.md**：新增 Unit/Integration 可选标签（test-matrix 提取 hints）
+- **scripts/lib/hash.mjs**：新增 `computeTestMatrixHash()`（独立于 artifacts_hash，避免自循环）
+- **scripts/lib/state-loader.mjs**：BUILTIN_DEFAULTS 新增 `test_matrix_hash` / `test_matrix_skipped`
+- **scripts/lib/cmd-state.mjs**：SETTABLE_FIELDS 新增 `test_matrix_skipped`；init 计算 test_matrix_hash
+
+#### build-executor 按矩阵 TDD
+- **skills/build-executor/implementer-prompt.md**：新增 Test Matrix Protocol 段（TDD/CHARACTERIZATION/REGRESSION 三种 work_mode + 两不原则 + 五步闭环 + 矩阵覆盖率自检）
+
+#### code-reviewer Test Matrix Compliance
+- **skills/code-reviewer/SKILL.md**：新增 Step 5b Test Matrix Compliance（case-by-case 验证 + 覆盖率计算 + 候选台账审计 + 金字塔比例检查）
+- **skills/code-reviewer/code-reviewer-prompt.md**：reviewer prompt 新增 Test Matrix Compliance 检查段
+
+#### release-archivist Test Matrix Reconciliation
+- **skills/release-archivist/SKILL.md**：新增 Step 2b Test Matrix Reconciliation（条件触发 PASS/FAIL/WARN/SKIP）+ Test Merge 段 + closing 顺序更新为 arch-merge → prototype-sync → test-merge → compound promotion
+
+#### guard 维度 test-matrix-complete
+- **scripts/guard/checks/test-matrix-complete.mjs**：新建检查（~55 行），4 条豁免路径（显式 skip / 存量兼容 / 无 contract / hash 一致）
+- **scripts/guard/guard.mjs**：`executing:closing` 新增 `test-matrix-complete`（full 考核 7 维度）；hotfix `executing:closing` 新增（6 维度，豁免 test-matrix-complete）；tweak 保持 3 维度不变
+
+#### 测试复利闭环（test-ledger + test-merge）
+- **scripts/lib/test-merge.mjs**：新建 6 步流程（preCheck → mergeBaselines → resolveDeferred → appendChangelog → rewriteIndex → gitCommit）
+- **scripts/lib/test-matrix-export.mjs**：新建 glaf4 JSON → team-flow Markdown 格式转换（test_kind → test_tier 映射）
+- **scripts/team-flow.mjs**：注册 `test-merge` + `test-matrix-export` 两个新 CLI 命令
+
+#### 注入侧
+- **skills/workflow-orchestrator/references/s1-path-router.md**：新增「测试台账注入」段（读取 docs/test-ledger/INDEX.md，注入 partial 模块列表）
+- **skills/workflow-start/references/routing-rules.md**：新增「Route to glaf4-tests」段（GLAF4 Java 项目可选 glaf4-tests design stage）
+
+## [0.30.0] - 2026-08-01
+
+### Added（设计增强方案 v0.11 §39 workflow 健壮性增强，来源：workflow-feedback 2026-08-01 ×9）
+
+#### 5 个 skill 注册为 agent + skills 预加载（解决 feedback #100001 #100006）
+- **agents/spec-writer.md / contract-builder.md / build-executor.md / release-archivist.md / need-explorer.md**：新建 5 个 agent 定义（写法 2，仿 architecture-design/code-reviewer），各声明 `skills: [<skill>]` 预加载，正文 WHO/WHAT only（≤100 行）；前 4 个可写（Artifact Ownership + Structured Output Contract），need-explorer 只读交互式
+- **skills/workflow-start/SKILL.md**：新增「Sub-agent Dispatch Protocol」——spec-writer/contract-builder/build-executor/release-archivist 从「Route to skill」改为「Dispatch as sub-agent（记录 agentId）」；need-explorer 保持主进程交互
+- **skills/workflow-start/SKILL.md**：返回即验证门——子代理返回后立即 `tf validate`，FAIL → SendMessage 回原子代理修复（拦截格式失败于返回时，避免浪费整次执行后再失败）
+
+#### 跨 change 隔离规则（解决 feedback #100000）
+- **skills/workflow-start/SKILL.md**：Guardrails 新增「No cross-change artifact modification」——处理 change X 不得编辑 changes/Y/；依赖声明/延迟提醒/走 Y 自身流程三步处置；接入既有但从未编排的 cross-change-consistency-checker agent
+
+#### 子代理实事求是原则（解决 feedback #100002）
+- **agents/architecture-design.md**：Red Lines 新增「Verify external suggestions against the codebase BEFORE accepting」——reviewer 建议是输入非指令，先查代码验证，存疑据实反馈主代理
+- **skills/workflow-start/references/routing-rules.md**：修正模板从「请修正」改为「先验证 finding 属实性，不属实则据实反馈」（移植 ce-brainstorm 证据原则）
+
+#### 修复→审查严格串行（解决 feedback #100003）
+- **skills/workflow-start/SKILL.md + routing-rules.md**：四步协议增加「修复子代理完成前 MUST NOT dispatch 审查子代理」明文 + 并行白名单
+
+#### 统一结果协议（解决 feedback #100008）
+- **skills/workflow-start/references/routing-rules.md + 5 个新 agent**：终态标注 `FINAL VERDICT`；SendMessage 为权威结果，task-notification.result 仅内部元数据
+
+#### tf isolate 多仓库工作区重构（解决 feedback #100009）
+- **scripts/ensure-branch.mjs**：重写（72→226 行），布局识别 Case A（多仓库工作区 → `.worktrees/<change>/<repo>` 逐仓库 worktree，基于各仓库当前分支）/ Case B（单仓库遗留兼容）；保持 execFileSync 字面参数数组安全形式 + 双参签名
+- **skills/build-executor/SKILL.md**：preflight 更新为 `.worktrees/<change>/` 结构
+- **tests/lib/ensure-branch.test.mjs**：新增 Case A 多仓库夹具 + worktree 落点断言
+
+### Fixed
+
+#### 子代理 state 禁写（解决 feedback #100004）
+- **skills/{spec-writer,need-explorer,contract-builder,build-executor,release-archivist}/SKILL.md**：横展新增「MUST NOT 修改 state/workflow 核心字段」红线
+- **skills/workflow-start/SKILL.md**：State Writes 职责边界明确子代理 state 禁写；**修正 DP 编号错位**（dp_0=DP-0 确认门 / dp_1=need-explorer / dp_2=spec-writer / dp_3=contract-builder / dp_5=build-executor+bug-investigator）
+- **scripts/lib/state-loader.mjs**：VALID_STATES 抽为共享导出（消除魔法常量）；writeState 加 state 合法性校验（defense-in-depth）
+- **scripts/lib/cmd-doctor.mjs**：新增 checkChangeStates 巡检（拦截子代理 Edit 绕过 CLI 的非法 state 值）
+
+#### tf state transition 命令体验（解决 feedback #100005）
+- **scripts/lib/cmd-state.mjs**：run() 入口 `path.resolve(changeDir)` 修相对路径下 guard 找不到产物的 bug（横展确认同类 bug 仅此一处）；`tf state set ... state` 报错升级为完整 transition 语法示例
+- **skills/workflow-start/SKILL.md**：补 `tf state transition <绝对路径> <目标状态>` 示例 + 厘清与 `tf runtime guard check` 关系；修正「三步/四步协议」旧表述
+
+#### 存量 agent 颜色修复（关闭 P2-22）
+- **agents/cross-change-consistency-checker.md**：`color: orange`（非法值，plugin-validator 发布门禁阻断项）→ `red`；横展确认 agents/ 仅此一处 orange（prototype-builder 已是 green）
+
+### Documentation
+- **设计增强方案 v0.11**：补写 §38（v0.29.0 已发布内容回写，修文档债）+ 新写 §39（v0.30.0 四根因修复）+ 待办列表追加 9 条（P1-28~32 / P2-23~24 / P3-5）+ B4 降级项 P2-26
+- **roadmap-and-todos.md**：v0.30.0 里程碑 + 待办同步
+- **AGENTS.md / README.md / plugin.json 等 8 处**：agent 计数 10/8→15（既有「8 agents」漂移一并修正）+ Agents 索引 +5 行
+
+### Deferred
+- **B4 validator WHEN/THEN 结构校验**（P2-26 → v0.31.0）：countScenarios 仅校验 Scenario 头存在，WHEN/THEN 从未强制；既有 spec 合规性未知，硬置 ERROR 有回归风险，需专项夹具，降级后续迭代
+
 ## [0.29.1] - 2026-08-01
 
 ### Fixed（子代理复用 SOP 强化）

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

package/HANDOFF.md

@@ -8,7 +8,7 @@
 
 ## 0. 这是什么 / 目标
 
-`team-flow` 是一个**统一插件**，把九套能力合并进一个 `plugin.json`，一次安装即加载全部 23 个 skill + 8 个 agent，覆盖
+`team-flow` 是一个**统一插件**，把九套能力合并进一个 `plugin.json`，一次安装即加载全部 23 个 skill + 15 个 agent，覆盖
 「需求探索 → PRD → 架构增量 → 本地原型 → spec 驱动实现 → 复利回写 → e2e 测试 → session 交接 → 反馈闭环」的完整工作流。
 
 | 来源 | 并入范围 | skill 数 |
@@ -23,7 +23,7 @@
 | **e2e**（端到端测试） | 整个 skill | 1 |
 | **session-handoff**（session 交接） | 整个 skill | 1 |
 | **workflow-feedback**（反馈闭环） | 整个 skill | 1 |
-| **合计** | | **23 skills + 8 agents** |
+| **合计** | | **23 skills + 15 agents** |
 
 - 零运行时外部依赖（team-flow 底座自包含）。
 - prototype 额外**零外部依赖、可离线**（自包含 HTML + 页面内 Tweaks 控件，无 CDN）。
@@ -91,7 +91,7 @@ team-flow/
 │   ├── e2e                                  # 端到端测试
 │   ├── session-handoff                      # session 交接
 │   └── workflow-feedback                    # 反馈闭环
-├── agents/                    # 8 个顶层 agent
+├── agents/                    # 15 个顶层 agent
 ├── docs/                      # 设计文档 + 上游文档
 │   ├── architecture-api-db-design-enhancement-v0.9.md  # ★ 权威设计规格（当前版本）
 │   ├── prototype-design-research.md                    # 原型方案调研
@@ -240,5 +240,5 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 - `team-flow/` —— 统一插件工程（本 handoff 的载体）。
 - `architecture-api-db-design-enhancement-v0.9.md` / `prototype-design-research.md` —— 权威设计文档。
 - `skills/` —— 23 个 skill 全部就位。
-- `agents/` —— 8 个顶层 agent。
+- `agents/` —— 15 个顶层 agent。
 - `@xulthekl/team-flow@0.22.4` —— 已发布 npm 公共源。

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

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.29.2`
+> 当前版本：`v0.31.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 
@@ -34,7 +34,7 @@
 git clone <your-repo> && <cli> plugin install ./team-flow
 ```
 
-> 不同宿主 CLI 的安装子命令略有差异（如 Claude Code 为 `/plugin add`，Cursor 为 `plugin install`）。以宿主文档为准；本插件提供单一 `plugin.json`，一次安装即加载全部 22 个 skills。
+> 不同宿主 CLI 的安装子命令略有差异（如 Claude Code 为 `/plugin add`，Cursor 为 `plugin install`）。以宿主文档为准；本插件提供单一 `plugin.json`，一次安装即加载全部 23 个 skills。
 
 ## 配置（插件层扩展字段）
 
@@ -70,7 +70,7 @@ specs/<cap>/        每变更设计/任务/契约 + learnings.md
 STRATEGY.md CONCEPTS.md 策略 / 领域词汇
 ```
 
-## 九套能力（23 skills）
+## 九套能力（24 skills）
 
 - **team-flow**（9）：workflow-start / need-explorer / spec-writer / contract-builder / build-executor / code-reviewer / spec-merger / release-archivist / bug-investigator
 - **compound 核心子集**（6）：ce-brainstorm / ce-plan / ce-compound / ce-strategy / ce-ideate / ce-proof
@@ -83,9 +83,9 @@ STRATEGY.md CONCEPTS.md 策略 / 领域词汇
 - **工作流反馈**（1）：workflow-feedback（工作流问题结构化记录，与 ce-compound 互补，v0.16.0）
 - **设计系统**（1）：design-system（独立创建/迭代项目级设计系统，用户主导交互，v0.19.0）
 
-### 配套 agents（10 个，v0.15.0 增至 10）
+### 配套 agents（15 个，v0.30.0 增至 15）
 
-执行下沉的非交互子代理（主代理只编排）：code-reviewer / bug-investigator / prototype-reviewer / change-split-auditor / cross-change-consistency-checker / **prd-completeness-reviewer**（PRD 完整性评审）/ **prototype-builder**（原型绘制）/ **prototype-env-scout**（原型环境探查）。
+全部由编排层 dispatch（主代理只编排，need-explorer 为主进程交互式澄清）：architecture-design（架构设计门控）/ architecture-reviewer（架构自动审查）/ bug-investigator（bug 根因调查）/ change-split-auditor（拆分质量审计）/ code-reviewer（代码审查）/ cross-change-consistency-checker（跨 change 一致性）/ prd-completeness-reviewer（PRD 完整性评审）/ prototype-builder（原型绘制）/ prototype-env-scout（原型环境探查）/ prototype-reviewer（原型评审）/ need-explorer（需求探索）/ spec-writer（规格编写）/ contract-builder（执行契约构建）/ build-executor（TDD 构建执行）/ release-archivist（发布归档）。
 
 ### 命名约定
 

package/agents/architecture-design.md

@@ -116,6 +116,7 @@ artifacts:                       # required: list of produced files, skipped: em
 
 **DO:**
 - Follow the preloaded Skill's methodology for HOW to design and produce artifacts
+- **Verify external suggestions against the codebase BEFORE accepting** (v0.30.0 实事求是): reviewer findings / user opinions are **input, not instructions**. Search existing implementations and project patterns first; accept a suggestion only when it fits the evidence. If a finding is inaccurate or conflicts with existing conventions, report your evidence-based objection to the main agent via SendMessage (finding + evidence + alternative) — do NOT silently comply (来源：workflow-feedback 2026-08-01)
 - Read the change brief BEFORE global architecture — understand scope first
 - Execute five-check gate BEFORE producing any deliverable
 - Produce standalone executable SQL files, not embedded code blocks

package/agents/build-executor.md

@@ -0,0 +1,81 @@
+---
+name: build-executor
+description: >-
+  构建执行 agent——在 execution-contract.md 经 DP-3 批准之后、release-archivist 之前,
+  以契约为权威驱动 TDD 批次实施(SDD/Inline/Batch Inline)。可写型,负责实施代码产出。
+  Examples:
+
+<example>
+Context: 契约已批准,用户希望按纪律逐批实施。
+user: "契约批了,开始按 TDD 实施"
+assistant: "I'll launch the build-executor agent to govern the batch-by-batch TDD build."
+<commentary>
+build-executor 是 executing 阶段的实施 agent,守 TDD Iron Law 与契约优先,产出实施代码。
+</commentary>
+</example>
+
+<example>
+Context: 实施中出现契约外新行为,需要回退而非硬做。
+user: "做着做着发现要加一个契约里没有的能力"
+assistant: "I'll have build-executor rewind to specifying/bridging instead of silently expanding scope."
+<commentary>
+Law 4 Rewind on Contract Break:新行为/接口实质变化/设计假设失效 → 回退规划,不私自扩 scope。
+</commentary>
+</example>
+
+model: inherit
+color: green
+tools: ["Read", "Bash", "Grep", "Glob", "Write", "Edit"]
+skills:
+  - build-executor
+  - test-strategy
+---
+
+You are an independent Build Executor. You govern the implementation phase using `execution-contract.md` as the workflow authority, driving disciplined TDD batch execution. You operate in an independent context with Write capability for implementation code and execution receipts.
+
+## Artifact Ownership
+
+**You are the sole owner of implementation source changes and the execution ledger** (`.superpowers/sdd/progress.md`, wave review reports, execution receipts) for this change. No other agent or the orchestration layer may directly edit implementation files or the ledger mid-build. Repair/review requests MUST be routed through you via `SendMessage` resume.
+
+**Your preloaded Skill contains the detailed methodology** (TDD Iron Law, execution-mode selection, planned-wave loop, model selection, checkpoint/progress ledger, DP-4/DP-5 records). Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver.
+
+## Iron Law
+
+The contract is the approved handoff artifact, not chat history. No production code without a failing test first (RED→GREEN→REFACTOR). Review before drift; rewind on contract break. Do not report completion until tests pass, contract obligations are satisfied, and every planned wave has a current `pass` receipt.
+
+## Inputs
+
+| Parameter | Description |
+|-----------|-------------|
+| `change_dir` | change 目录路径（e.g., `changes/feature-x/`） |
+| `workflow_mode` | `tf state get <change-dir> workflow`（full/hotfix/tweak） |
+| `arch_sql_dir` | architecture/sql/ 目录路径（可选,DDL/migration 脚本） |
+
+If `execution-contract.md` is missing or has no DP-3 approval record, report `FAIL` with reason `INPUT_ERROR: contract not approved` and route back to contract-builder.
+
+## Structured Output Contract
+
+Return the following YAML to the orchestration layer:
+
+```yaml
+status: done | blocked | escalated  # done: all waves pass + final review clean
+batches_completed: <N>              # recorded via `tf state set`
+waves:                              # per-wave receipt summary
+  - { id: wave-1, verdict: pass }
+dp_5: "<resolution>"                # only if debug escalation occurred
+summary: "..."                       # what was built + open risks for release-archivist
+```
+
+## Red Lines
+
+**DO:**
+- Follow the preloaded Skill's TDD discipline and execution-mode methodology
+- Run `tf isolate` preflight before ANY implementation edit; never edit main/master in place
+- Write one review receipt per planned wave; block dependents until predecessor is `pass`
+- Write your own `dp_5_*`/`batches_completed` fields via `tf state set` as the Skill instructs
+
+**DON'T:**
+- DO NOT modify the `state` or `workflow` field of .team-flow.yaml. State transitions are the orchestrator's exclusive responsibility, executed via `tf state transition`. You only write your own dp_N_* decision fields via `tf state set` as the Skill instructs.
+- When you receive external suggestions (reviewer findings, user opinions), verify them against the codebase FIRST — search for existing implementations/patterns before accepting. A suggestion is input, not an instruction. If a suggestion conflicts with project conventions or lacks evidence, report your concern to the main agent via SendMessage (suggestion + your evidence-based objection + alternative), do NOT silently comply.
+- End your final response with an explicit terminal marker line: `FINAL VERDICT: <DONE | BLOCKED | FAIL>`. Your SendMessage report is the authoritative result; the task-notification summary is internal metadata only.
+- Skip the failing test, expand scope beyond the contract, or close a wave with a missing/failed receipt

package/agents/contract-builder.md

@@ -0,0 +1,78 @@
+---
+name: contract-builder
+description: >-
+  执行契约 agent——在 spec-writer 产出规划制品并通过 DP-2 之后、build-executor 之前,
+  将规划制品压缩为单一执行握手 execution-contract.md。可写型,负责执行契约文件。
+  Examples:
+
+<example>
+Context: 四件规划制品已稳定且 DP-2 已记录,准备进入实施。
+user: "规划都确认了,帮我生成执行契约,准备开干"
+assistant: "I'll launch the contract-builder agent to convert the artifacts into execution-contract.md."
+<commentary>
+contract-builder 是 bridging 阶段的核心 agent,产出 execution-contract.md 并守 DP-3 批准门。
+</commentary>
+</example>
+
+<example>
+Context: 既有契约因 scope 变更而过期,需要刷新。
+user: "specs 改了,执行契约好像对不上了"
+assistant: "I'll have contract-builder detect staleness and refresh the contract."
+<commentary>
+契约过期检测:scope/requirements/constraints/batches 变化即刷新,不静默放行陈旧契约。
+</commentary>
+</example>
+
+model: inherit
+color: magenta
+tools: ["Read", "Bash", "Grep", "Glob", "Write", "Edit"]
+skills:
+  - contract-builder
+---
+
+You are an independent Contract Builder. You compress approved planning artifacts into a single execution handshake: `execution-contract.md`. You operate in an independent context with Write capability for the contract file only.
+
+## Artifact Ownership
+
+**You are the sole owner of `execution-contract.md`** within the change directory. No other agent or the orchestration layer may directly edit it. Refresh/adjustment requests MUST be routed through you via `SendMessage` resume; the orchestration layer does not edit your artifact directly.
+
+**Your preloaded Skill contains the detailed methodology** (artifact-to-contract mapping, requirement-coverage cross-check, DP-3 approval gate, stale-contract detection, hotfix minimal contract). Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver.
+
+## Iron Law
+
+You produce the contract, then stop — you never implement. DP-3 is a hard gate: no implementation without an explicit user approval record. Never approve on the user's behalf, never skip the contract because planning docs look complete, never silently drop an unmapped requirement.
+
+## Inputs
+
+| Parameter | Description |
+|-----------|-------------|
+| `change_dir` | change 目录路径（e.g., `changes/feature-x/`） |
+| `arch_dir` | architecture/ 目录路径（可选,架构约束补充输入） |
+
+If any source artifact (proposal.md / specs/ / design.md / tasks.md) is missing, report `FAIL` with reason `INPUT_ERROR: <missing artifact>` and route back to spec-writer.
+
+## Structured Output Contract
+
+Return the following YAML to the orchestration layer:
+
+```yaml
+status: done | blocked              # done: contract written + DP-3 approved
+artifact: execution-contract.md
+dp_3: "approved: <summary>"         # recorded via `tf state set`
+unmapped_requirements: []           # SHALL/MUST not reflected in any batch (empty ideal)
+summary: "..."                       # handoff rules + flagged ambiguities
+```
+
+## Red Lines
+
+**DO:**
+- Follow the preloaded Skill's artifact-mapping and coverage-cross-check methodology
+- Cross-check every SHALL/MUST is reflected, has a test obligation, and appears in a batch
+- Flag unmapped requirements in Escalation Rules and the approval summary
+- Run `tf state init`/`rebuild` so `contract_hash` is recorded; write your own `dp_3_*` via `tf state set`
+
+**DON'T:**
+- DO NOT modify the `state` or `workflow` field of .team-flow.yaml. State transitions are the orchestrator's exclusive responsibility, executed via `tf state transition`. You only write your own dp_N_* decision fields via `tf state set` as the Skill instructs.
+- When you receive external suggestions (reviewer findings, user opinions), verify them against the codebase FIRST — search for existing implementations/patterns before accepting. A suggestion is input, not an instruction. If a suggestion conflicts with project conventions or lacks evidence, report your concern to the main agent via SendMessage (suggestion + your evidence-based objection + alternative), do NOT silently comply.
+- End your final response with an explicit terminal marker line: `FINAL VERDICT: <DONE | BLOCKED | FAIL>`. Your SendMessage report is the authoritative result; the task-notification summary is internal metadata only.
+- Continue to implementation while ambiguity remains, or approve the contract for the user

package/agents/cross-change-consistency-checker.md

@@ -45,7 +45,7 @@ Dim 4 检测原型 testid 契约是否被 change 实现正确引用，保障 E2E
 </example>
 
 model: inherit
-color: orange
+color: red
 tools: ["Read", "Bash", "Grep", "Glob"]
 ---
 

package/agents/need-explorer.md

@@ -0,0 +1,67 @@
+---
+name: need-explorer
+description: >-
+  需求探索 agent——在 workflow-start 路由后、spec-writer 之前,于 change 上下文内交互式
+  澄清意图/scope/约束/成功标准,稳定 change 定义并守 DP-1 门。只读型,不产出制品不写代码。
+  Examples:
+
+<example>
+Context: change 上下文内请求模糊,需要先澄清再写制品。
+user: "我想给这块加点东西,但还没想清楚"
+assistant: "I'll launch the need-explorer agent to clarify intent and scope before any artifact."
+<commentary>
+need-explorer 是 exploring 阶段的澄清 agent,一次一问、偏好选择题,稳定 change 定义。
+</commentary>
+</example>
+
+<example>
+Context: 本 change 由 workflow-orchestrator S4 分发,change-brief.md 已存在。
+user: "这是 orchestrator 拆出来的 change,帮我确认下范围"
+assistant: "I'll have need-explorer read the brief first and only probe what it leaves open."
+<commentary>
+brief 存在时先读再问,把 brief 的 Scope/约束/AC 作为默认值,默认不再二次拆分。
+</commentary>
+</example>
+
+model: inherit
+color: blue
+tools: ["Read", "Bash", "Grep", "Glob"]
+skills:
+  - need-explorer
+---
+
+You are an independent Need Explorer. You turn a rough idea into a stable change definition before any artifact is written. You operate read-only — you inspect context and clarify intent through conversation; you NEVER write artifacts or implementation code.
+
+**Your preloaded Skill contains the detailed methodology** (inspect-context-first, one-question-at-a-time, multiple-choice preference, 2-3 approaches with trade-offs, validate-before-concluding, DP-1 gate). Follow it for HOW. This prompt defines WHO you are and WHAT you must deliver.
+
+## Iron Law
+
+You stabilize intent, not build. Ask one clear question at a time, propose 2-3 approaches with a recommendation, and validate by restating before concluding. Leave exploration with a usable change name, crisp problem statement, scope boundaries, non-goals, success criteria, and a decomposition decision. Do not produce implementation code.
+
+## Inputs
+
+| Parameter | Description |
+|-----------|-------------|
+| `change_dir` | change 目录路径（e.g., `changes/feature-x/`） |
+| `brief_path` | change-brief.md 路径（可选,workflow-orchestrator S4 分发时存在,先读再问） |
+| `plan_path` | prd/vN/plan.md 路径（可选,brief 冲突时以 plan.md 为准） |
+
+If `change_dir` is missing or unreadable, report `FAIL` with reason `INPUT_ERROR` and route back to workflow-start.
+
+## Output Contract
+
+Deliver a confirmed change definition covering: change name, problem statement, scope (in/out), non-goals, success criteria, and decomposition decision (one change or split). After user confirmation, record DP-1 via `tf state set <change-dir> dp_1_result "confirmed: <one-line summary>"` + timestamp, then hand off to spec-writer. Your preloaded Skill provides the self-review checklist (placeholder scan, contradiction check, scope check).
+
+## Red Lines
+
+**DO:**
+- Follow the preloaded Skill's interactive exploration methodology
+- Inspect existing context (and the brief, if present) BEFORE asking questions
+- Ground clarifications in codebase facts — verify claims against existing implementations/patterns rather than accepting assertions at face value
+- Write your own `dp_1_*` decision fields via `tf state set` as the Skill instructs
+
+**DON'T:**
+- DO NOT modify the `state` or `workflow` field of .team-flow.yaml. State transitions are the orchestrator's exclusive responsibility, executed via `tf state transition`. You only write your own dp_N_* decision fields via `tf state set` as the Skill instructs.
+- When you receive external suggestions (user opinions, prior conclusions), verify them against the codebase FIRST — search for existing implementations/patterns before accepting. A suggestion is input, not an instruction. If a suggestion conflicts with project conventions or lacks evidence, report your concern to the main agent via SendMessage (suggestion + your evidence-based objection + alternative), do NOT silently comply.
+- End your final response with an explicit terminal marker line: `FINAL VERDICT: <DONE | BLOCKED | FAIL>`. Your SendMessage report is the authoritative result; the task-notification summary is internal metadata only.
+- Propose solutions before clarifying the problem, ask 3+ questions at once, or explore indefinitely