@yangdcm/dsh-expert-team 1.1.0

package/skills/expert-team/assets/templates/STATE.json

@@ -0,0 +1,10 @@
+{
+  "runId": "",
+  "phase": "clarify",
+  "status": "running",
+  "mode": "one-shot",
+  "deliverable": "code+artifacts",
+  "coverage": [],
+  "members": [],
+  "updatedAt": ""
+}

package/skills/expert-team/assets/templates/SUMMARY.md

@@ -0,0 +1,25 @@
+# 任务总结（{{run-id}}）
+
+> deliver 阶段由 lead 填写；用 write 落盘，让用户在聊天框可点击预览交付结果。
+> ⚠️ 工件引用只用**文件名**（如 `SUMMARY.md`/`看板.md`/`SPEC.md`，一个名字一次）；带目录的完整路径不会变成可点击。
+
+## 结论
+
+（是否全部交付 / 是否通过校验 / 整体一句话）
+
+## 各任务交付
+
+- **Task 1（commit xxx）**：
+- **Task 2（commit yyy）**：
+
+## 关键改动
+
+（改动文件与要点）
+
+## 评审与测试结论
+
+（REVIEW.md / TEST.md 结论：问题数、通过/返工）
+
+## 经验与下一步
+
+（可选）

package/skills/expert-team/assets/templates/TASK.md

@@ -0,0 +1,23 @@
+# 任务
+
+> 目标：（由 /team 命令填充）
+
+- 模式：one-shot / persist
+- 交付：code+artifacts / artifacts-only
+- 固定角色：pm, architect, backend, frontend, qa
+
+## 完成标准（lead 在 clarify 结束时填写，deliver 按它验收）
+
+- （验收必须满足的客观条件，如「9 个未达标页全部重设计并通过 token 断言」）
+
+## 禁止操作（不可越界的事项，写进每个角色的约束）
+
+- （如「不能改 admin-v2 接口 / 不能动数据库迁移 024 / 不发布不部署 / 不破坏既有 76 项测试」）
+
+## 状态
+
+待编排者按 expert-team skill 推进。
+
+## 交付结论
+
+（deliver 阶段由 lead 填写）

package/skills/expert-team/assets/templates/TASKS.json

@@ -0,0 +1,3 @@
+{
+  "tasks": []
+}

package/skills/expert-team/assets/templates/TEST.md

@@ -0,0 +1,9 @@
+# 测试（TEST）
+
+## 结论
+
+（通过 / 失败）
+
+## 命令与结果
+
+## 覆盖

package/skills/expert-team/assets/templates//344/273/273/345/212/241/347/234/213/346/235/277.md

@@ -0,0 +1,23 @@
+# 任务看板（{{run-id}}）
+
+> lead 维护：每个阶段结束时用 write 更新，让用户随时点击预览「任务安排 + 执行状态」。
+
+## 当前阶段
+
+（澄清 clarify / 调研 research / 设计 design / 规格评审 spec-review / 方案确认 / 实现 implement / 审查 review / 测试 test / 交付 deliver）
+
+## 覆盖率（coverage matrix）
+
+> design 阶段把用户每个显式约束映射到 ≥1 条任务，这里锁定，防止“用户说 5 件事、只做了 3 件”。
+
+| 用户约束 | 覆盖任务 |
+|---|---|
+|  |  |
+
+## 任务计划与状态
+
+| # | 任务 | kind | 负责人 | 状态 | round / verdict | 依赖 | 说明 |
+|---|---|---|---|---|---|---|---|
+| 1 |  |  |  | 待开始 |  |  |  |
+
+> 状态机：`pending → claimed → in_progress → completed｜failed｜cancelled`；`rework` 为 review 返工过渡态。依赖只认上游 `completed`。review/requirements 只有 `verdict=pass` 才 `completed`；非 pass 自动开 `repair-N` + `review-N+1`。

package/skills/expert-team/references/EFFICIENCY.md

@@ -0,0 +1,79 @@
+# 效率规则
+
+「专家团」的高效来自结构，而不是堆算力。编排者必须遵守。
+
+## 1. 并行扇出
+
+- implement 阶段的后端/前端/补位角色**并行**启动，不串行等待。
+- 无依赖的任务用 `workflow` 的 `parallel()`，或 persist 模式下同时 `subagent run_in_background` 多个成员。
+- 有依赖的阶段（clarify→design、review 依赖 implement）保持串行门控。
+
+## 2. 阶段门控防上下文漂移
+
+- 每个角色**只读上一阶段产物 + 直接输入**，禁止重读整条对话历史。
+- 交接走结构化值 + 工件文件，二者一致。
+- 好处：子 agent 上下文小、请求前缀稳定、KV cache 复用高。
+
+## 3. 结构化交接
+
+- 每个角色带 JSON `schema` 返回，下游据此解析，不回读原始文本。
+- schema 只声明需要下传的字段（详见各角色模板），不要塞大文本。
+
+## 4. 角色守界（toolFilter 纪律）
+
+| 角色 | 能 | 不能 |
+|---|---|---|
+| pm / architect | 读、写自己工件、ask_user_question | 改代码、跑实现命令 |
+| backend / frontend | 写/编辑代码、bash 自检、读契约 | 改 SPEC/PLAN 契约、评审他人 |
+| qa | 读、跑测试/构建、写 REVIEW/TEST | 改业务代码 |
+
+守界既是质量保证，也是效率：防止角色做超范围的事、产生返工与上下文浪费。
+
+## 5. 限深
+
+- 委派深度 ≤ 2（团队不递归组建子团队）。**`maxDepth` 是子代理深度的绝对上限**（`childDepth = parentDepth + 1 ≤ maxDepth`）：角色工具写 `1`（lead 第 0 层 → 角色第 1 层，且角色不能再派）；**写 `0` 会让所有角色工具报 `subagent depth 1 exceeds maxDepth 0`**。通用 `subagent` 保持平台默认 `3`，但协议上不递归组建子团队。
+- 需要更大规模时，先问用户。
+
+## 6. 稳定前缀
+
+- 角色 prompt 固定（来自 ROLES.md 模板），工件路径固定。
+- 避免把易变文本重复注入；状态变化写进 `STATE.json` 而非每条消息都带全量状态。
+
+## 7. 不空转
+
+- 阶段产物一次到位：pm 一次性把验收标准定清，architect 一次性把契约定清。
+- review 返工只重跑受影响角色，不整队重来。
+- deliver 只做一次最终校验 + 汇总。
+
+## 8. 后台优先
+
+- 能后台就后台：persist 模式用可继续子 agent，编排者不阻塞等待；成员结算通知会带回结论。
+- one-shot 批量交付才用会阻塞的 `workflow`（用户明确「做完再回来」）。
+
+## 9. 自动调度（状态机 + 依赖门控）
+
+- **状态机**：任务 `pending → claimed → in_progress → completed | failed | cancelled`，`rework` 为 review 返工过渡态。终态（`completed/failed/cancelled`）只读。
+- **派工与结算即时回写 `TASKS.json`**（头号纪律，日志分析实证）：派工→任务 `claimed/in_progress`；成员完成→`status=completed` + `changedPaths` + `verify`。只更新看板/聊天 ≠ 更新状态；阶段进入 implement 后「依赖已就绪却仍 pending」= 状态冻结违规（host 门禁 + 浮层红条）。
+- **契约冻结再并行（签名级）**：implement 前 architect 先产出签名级契约（字段/接口/DDL/状态机含豁免与边界），backend/frontend 只读它实现——并行角色在边界上的分歧必须在契约里前置冻结（历史 run：DDL 15 项分歧、MASK_KEYS 子串误伤导致返工）。
+- **大工件不走 workflow 聚合返回**：超大内容（schema 全文/设计长文）塞进聚合返回值会被截断并丢失后段角色；用子角色 `send_message` 单发、拆分小 workflow，或只回位置引用由 lead 读盘。
+- **依赖只认 completed**：派工前用 `unsatisfiedDependencies()` 校验；上游仍 `pending/claimed/in_progress` 的任务一律不派；`failed/cancelled` 永不解锁下游。
+- **一个成员一次一个未完成任务**：别让同一个成员同时持有两个在办任务。
+- **空闲自动领题**：persist 模式下，成员 idle（`list_agents` 为空闲 / 收到结算）后自动领下一个依赖已满足的 `pending` 任务，别等到 lead 显式点名。
+- **attempt/attemptId**：每次派工/转派 `attempt+1`、设新 `attemptId`；成员回报必须带当前 `attemptId`，**旧 attemptId 的迟到写入一律拒绝**；转派/接管先使旧 attempt 失效并等待旧成员安静。
+- **冷启动恢复**：run 恢复时对残留开放 attempt 自动重试一次；别把停驻 attempt 当可无限重派的 `pending`。
+
+## 10. 不要自己审自己 / 不无限互审
+
+- reviewer 不审自己刚写的实现/修复；修复者不把 review 标 pass；没有用户要求，不让 Captain 自己批准自己的实现。
+- review 非 pass 只重跑受影响实现 + 新建独立 review，不整队重来。
+- 达到 `maxReviewRounds` 后升级到用户，不无休止地“再来一轮”。**这条现在是代码强制**（`ROUND_LIMITS` + 违规码 `REWORK_LOOP_UNESCALATED` / `FINDING_REOPENED` + 写侧拒绝 `REWORK_LOOP_LIMIT`，见 PIPELINE.md「自动修复链」）；同一 finding 连续两轮未闭环 ⇒ 判**规格歧义**，升级用户裁定，不再派修复。
+- **返工预算意识**：一次 run 的返工轮数是**成本指标**。实证事故：某 run 68 任务 / 32 条 repair / maxRound=8，评审每轮都在**新增** finding（每轮还撤销约 8 条幻觉）——**验收面无界 + 噪声制造返工** 是循环的两个真实来源，解法是「边界前置到 SPEC」（见 pm 的「边界与禁止项」）与「撤销前置到派工前」（见 reviewer 职责 5），而不是加班修更多轮。
+
+## 11. 安全与守界（工具纪律 + 越界审计）
+
+> 说明：dsh 0.1.2-rc.1 无 PreToolUse/PostToolUse 这类插件级拦截 hook（仅 `fs/observed`/`tools/result` 事后事件）；成员的真正工具边界由 **expert-team preset 的 toolFilter** 保证，越界由**完成时 `changedPaths` 审计**兜底。本协议在编排层再加固。
+
+- **工具守界**：非实现角色（pm/architect/researcher/ui/reviewer/sec/docs）在 preset toolFilter 里不得有写业务代码/改文件工具，只读；qa/devops 只跑测试/构建/部署命令，dba 只做只读查询。越权工具已从 preset 移除；若遇通用 subagent 回退，写进 prompt 的 ROLES.md 守界条款同样适用。
+- **实现者只动 `inScope`**：每条实现/修复任务的 `inScope` 写清合法改动范围；实现者不得改 `outOfScope` 文件；完成时回报 `changedPaths`，lead 对照 `inScope` 审计，越界不得 `completed`。
+- **高危命令**：成员（尤其实现者）禁止执行 `rm -rf`、`sudo`、`chmod 777`、`git push --force` 等破坏性/生产命令；这些只由 lead 在**沙箱/受控终端**里跑（dsh sandbox 已启用时），且需用户确认。
+- **审计**：lead 把关键工具/文件变更链路记入 `RUN.log`（`tool:bash <cmd>`、`fs:write <path>`），形成可追溯审计；`/team learn` 会聚合高频错误/越界。

package/skills/expert-team/references/LOGGING.md

@@ -0,0 +1,82 @@
+# 运行日志与自我优化（LOGGING）
+
+团队运行期间必须持续记录，供后续迭代升级与自我优化。日志是**结构化、可 grep、可累加**的。
+
+## 三个产物
+
+| 文件 | 谁写 | 何时 | 用途 |
+|---|---|---|---|
+| `<run-dir>/RUN.log.md` | 编排者（lead）逐行追加 | 每完成一个阶段/角色/决策/卡点 | 单次运行的可回放轨迹 |
+| `<run-dir>/RETRO.md` | lead | deliver 阶段 | 本次复盘：快/慢/卡点/经验 |
+| `<cwd>/team/LEARNINGS.md` | lead 追加 | deliver 阶段（**run 开始前先读**） | 跨运行累积的可复用经验 |
+
+## 事件约定（RUN.log.md 每行一条）
+
+统一格式：`- [HH:MM:SS] <type> — <详情>`。`<type>` 固定用下列词，便于 grep/统计：
+
+| type | 触发时机 | 详情示例 |
+|---|---|---|
+| `run:started` / `run:resumed` | 命令自动写 | 目标/模式/交付/编制 |
+| `phase:<阶段名>`（**推荐**）；`phase:started` / `phase:completed` 仍兼容 | 每次阶段流转 | `phase:design — design (architect)` |
+| `role:invoked` | 启动某角色（workflow agent / 可继续成员） | `role=backend tool=subagent_backend id=<id>` |
+| `role:result` | 某角色返回 | `verdict=pass/rework/fail`、`blockers=`、`issues=` |
+| `first-runnable` | **首个最小可运行骨架落盘**（E1：run 开始 ≤10 分钟内，见 SKILL §7.32） | 冒烟命令 + 原始输出摘要 |
+| `ask:clarify` | clarify 向用户提问（**clarify 阶段每抛一个问题追加一行**，不要合并成一行） | 问题摘要 |
+| `answer` | 用户回答 | 答案摘要 |
+| `decision` | lead 做裁决/合并冲突 | 结论 + 理由 |
+| `scan:single-source` | **发现一处「同一事实多份拷贝」后当轮做完全仓总扫**（E3，见 SKILL §7.34） | `事实名 + 命中 N 处` |
+| `tokens:<scope>` | **可选**：记一次会话的 token 用量（P5 线；通常**不必写**——METRICS 直接读 DSH 会话遥测，见下） | `steps=62 in=2621 cache=177955 out=1132 peak=528246` |
+| `artifact` | 工件被写/改 | `SPEC.md written` |
+| `error` | 任何失败/卡点 | 角色 + 原因 |
+| `run:completed` | deliver 完成 | verdict + 交付清单 |
+
+要求：**每个阶段开始与结束、每个角色调用与返回，至少各记一行**；卡点/返工/裁决必须记（这是自我优化的核心素材）。
+补充（聚合器兼容性，2026-09-08 日志分析后定稿）：
+- **事件写成 `error:<子类>`（如 `error:workflow`/`error:external-write`）、`decision:<来源>`（如 `decision:user`）、`role:<角色>`（如 `role:pm`）；聚合器按「事件族」（冒号前那段）统计，子类保留用于定位根因**——METRICS 会渲染成 ``- `error:external-write` × 9 — <首条详情样例>``，所以子类要稳定、可归类，不要每次换词。
+- **阶段行统一写 `phase:<阶段名>`**（如 `phase:implement — 并行派工 …`、`phase:design — design (architect)`）。`phase:started` / `phase:completed` 这两种旧写法**只对 ASCII 阶段名兼容**：聚合器从详情里取**第一个 ASCII 词**再校验词表（`design (architect)` ⇒ `design`）。⚠️ **中文阶段名（如 `方案确认`）必须直接写 `phase:方案确认`** —— 兼容形式解析不出中文词，该行会被**整行跳过**（宁可不计，也不记成伪阶段）。阶段名必须落在流水线词表内（`clarify` / `research` / `design` / `spec-review` / `方案确认` / `implement` / `review` / `test` / `deliver`）；**解析不出、或不在词表内就整行跳过** —— 绝不会记成 `started`/`completed`/`backend` 这种伪阶段、把「阶段覆盖」这一节污染掉。（已登记 backlog：把兼容形式改为「先对词表做包含匹配、再退回 ASCII 词」，让中文阶段名在旧写法下也能计入。）
+- **`phase:review` / `phase:test` 是"冻结观测点"，漏写会让收尾时长整个隐形（E2）**：METRICS 的「收尾预算」节用**首个 `review`/`test` 阶段事件**把「实现期」与「冻结后收尾」切开（实现期 3h23m vs 收尾 3h35m 就是这样量出来的）。实测某真实 run **一条 review/test 事件都没写** ⇒ 那 3h35m 在指标上完全不存在。聚合器**不猜**：缺了就是「分不开」，单列成 ⚠️ 项 —— 也不要事后补写假事件。
+- **判决只认 `verdict=<token>`，合法 token 词表固定为：`pass` / `needs_revision` / `rework` / `fail` / `conditionally-pass`（等价写法 `conditional`、`conditionally` 也记 pass）**。三条硬规则：① **允许 markdown / 全角包裹**（`` verdict=`needs_revision` ``、`verdict=「needs_revision」`、`**verdict=needs_revision**` 都会被剥掉包裹后识别）；② **无法识别的 token 一律不计判决**（`verdict=foo`、`verdict=pass_unverified` 既不记 pass 也不记 rework，且**绝不回落**到从中文散文里猜判决 —— 那正是把 `needs_revision` 误判成 `pass` 的老 bug）；③ **只认 `verdict=`，`verdict:` 不算**。判决请按 token 写，别把结论只写在散文里。
+- **时间戳必须是实际时刻 `HH:MM:SS`，禁止 `[now]`**——`[now]` 会让聚合器丢事件（历史 run 全用 `[now]`，决策/阶段统计全部漏掉）。**E1 的「首个可运行产物耗时」直接依赖这条**：它 = `first-runnable` 的时间戳 − `run:started` 的时间戳，写成 `[now]` 就**算不出**（聚合器按「登记了但算不出」单列，不会退化成 0——退化成 0 会把"没测到"读成"很快"）。
+- **质量任务用 `kind: verification` 或 `kind: quality`，归属 `qa`/`reviewer`**，不要挂给实现者（历史 run 把 Q1 安全自检挂了 backend，被判归属违规）。写状态用 `/team task <id> <状态>` 一条命令回写。
+- **RETRO.md deliver 必填**（结果/时间与卡点/做得好的/做得慢的/可复用经验）——`/team check` 在 deliver/complete 时会检测模板占位并提示；复盘是自我学习的输入。
+
+### token 记账（P5 线 · 通常**不必写**）
+
+`/team learn` 生成的 METRICS 里有「token 成本与上下文峰值」一节，它的数**自动**来自 DSH 会话遥测
+（`~/.dsh/sessions/<workspace-slug>/<session>/session.v3.jsonl.zstd` 里每条 `assistant/message` 的 `usage`），
+归属靠「派工提示词里带的 **run 目录路径**」——**所以 lead 不需要为此额外记任何日志**。
+
+只有在**会话文件读不到**时（换机器跑、会话被清理）才需要手工补，写法：
+
+```
+- [HH:MM:SS] tokens:lead — steps=2279 in=6575499 cache=967380736 out=1646348 peak=799958
+- [HH:MM:SS] tokens:backend — steps=62 in=2621 cache=177955 out=1132 peak=528246
+```
+
+字段含义与**硬规则**：
+- 五个字段：`steps` 步数 · `in` **未缓存输入** · `cache` **缓存输入** · `out` 输出 · `peak` 单步 prompt 峰值（可选 `first` = 会话首步 prompt）。允许 `k`/`m` 后缀（`peak=426k`）。
+- `tokens:<角色>` 的 `<角色>` 用**规范英文 id**（`lead` / `pm` / `backend` / `qa` …），与 `role:` 事件同一套。
+- **字段名写错会让整行作废并计入报告的 ⚠️ 坏行数**（不再静默丢掉那一个字段）——近似拼法（`input=` / `cache_read=` / `total=`）都不认，请照上表写。
+- 也可以把用量挂在既有的 `role:` 行上：`- [HH:MM:SS] role:backend — tokens steps=62 in=2621 cache=177955 out=1132`。
+- **日志事件与遥测不混算**：某 run 有遥测就用遥测，没有才用日志事件，报告里会标明来源。
+- 为什么值得记：**prompt 体积 × 步数**才是成本主因（实测输出 tokens 只占总量的 0.25%~0.3%，99% 的输入是缓存读；一条 lead 会话累计 prompt 可达 **9.7 亿**、每步 prompt 中位数 **426K**）。有数才谈得上收缩。
+
+## 自我优化闭环
+
+1. **run 开始前**：lead 读 `<cwd>/team/LEARNINGS.md`（若存在），把相关经验融入本次编排（例如「上次前端接口契约不清导致返工，这次 design 阶段先把契约写到签名级」）。
+2. **run 过程中**：按上面事件约定持续记 RUN.log.md。
+3. **deliver**：写 RETRO.md（快/慢/卡点），并把「可复用经验」沉淀。经验**分两层**，写到不同文件（避免项目私有知识污染跨项目复用）：
+   - **团队/流程级**（跨项目可复用的编排教训，如「大工件别塞 workflow 聚合返回」「并行前先冻结契约」）→ 追加到**全局** `~/.dsh/expert-team/LEARNINGS.md`。
+   - **项目级**（本项目专属坑/环境/约定，如「本项目签名是 HMAC 非 RSA」「该模块测试环境要看 X」）→ 追加到 `<cwd>/team/LEARNINGS.md`。
+4. **落 Hindsight（跨项目召回）**：deliver 时用 `hindsight_ingest_document` 把本次「可复用经验」（RETRO 要点 + 蒸馏的 LEARNINGS，标题 `专家团经验 · <runId>`）保存一次，供其它会话召回；不要倒大段原始输出。
+
+LEARNINGS 每层都分两类沉淀（这是自我优化的核心）：
+   - **Team Skill**：`- [日期] <任务类型> → 最优派工顺序/角色是 <...>`（哪类任务用哪种派工顺序最顺、哪些角色可省）。
+   - **Expert Skill**：`- [日期] <角色/模块>：<历史坑/环境怎么起/注意事项>`（某模块测试环境怎么起、某接口有哪些坑）。
+
+## 原则
+
+- 只记**事实与结论**，不记大段原始输出（原始输出已在各角色 transcript/工件里）。
+- 日志是追加式，不要重写历史；时间戳用本地 `HH:MM:SS`。
+- **`role:result` 尽量写成 `role=<角色> verdict=<pass|rework|fail>`**（如 `role=backend verdict=rework`），让 `/team learn` 统计角色成败；即便不写该字段，聚合器也会尽力从文字推断（如「返工」「不一致」→ rework）。
+- 卡点与返工**必须如实记**——掩盖问题会破坏自我优化的数据基础。

package/skills/expert-team/references/PERSIST.md

@@ -0,0 +1,57 @@
+# persist 模式：持久化活成员协议
+
+`TASK.md.mode == persist` 时使用本协议（不用 `workflow`）。目标：把每个角色变成**可反复指挥、可跨会话恢复**的活成员。
+
+## 1. 启动成员
+
+为每个固定/补位角色启动一个**可继续**子 agent：
+
+- **优先用角色工具**（会话运行在「专家团模式」preset 时可用）：`subagent_pm` / `subagent_architect` / `subagent_researcher` / `subagent_ui` / `subagent_backend` / `subagent_frontend` / `subagent_dba` / `subagent_sec` / `subagent_reviewer` / `subagent_qa` / `subagent_devops` / `subagent_docs`。它们的 persona、toolFilter、maxDepth 已由配置保证——`prompt` 里只需给「本阶段任务 + 要读写/更新的工件」，`description` 用角色名。
+- **退回通用 `subagent`**（未运行 expert-team preset 时）：`prompt` 用 `ROLES.md` 里该角色的完整模板（含通用前缀，并把 `{{run-dir}}` 替换为真实路径、`{{role}}` 替换为角色名），`description` 用角色名。
+- `run_in_background` 默认 true。返回 `{ subagentId }` 后，把该 id 记进 `ROSTER.json.members[role]` 与 `STATE.json.members`。
+
+## 2. 指挥成员
+
+- 派活：`send_message(subagent_id, "<本阶段指令>")` —— 指令指向 `<run-dir>/` 的具体工件与要产出/更新的文件。
+- 看状态：`list_agents()` 看成员 running/idle/ready。
+- 打断：`interrupt_agent(agent_id)` 停当前轮（幂等）。
+- 收结论：成员结算时会推「settlement notice」带最终结论；也可用其 transcript（按 subagent id 读）取详细输出。
+- **冷恢复**：`list_agents` 里 `ready`（仅存于存储）的成员，用 `send_message` 冷恢复后继续；`interrupted`/停驻的 attempt 通过定向 message 续（不重铸）。
+
+### 2.5 成员直发消息与交接（定向分发，lead 仲裁）
+
+- **定向分发**：`send_message` 永远指向**具体成员 id**（`ROSTER.json.members[role]`），不要广撒。每条消息只含该成员需要的那一段工件契约/范围，避免上下文稀释。
+- **角色↔角色交接**：若后端实现中发现契约问题需要前端知道，**由你（lead）定向转发**——把后端 report 里的「需前端确认项」用 `send_message` 传给前端成员；成员之间不直接互发（保持 lead 仲裁线）。
+- **mailbox 语义（可选）**：成员 report 里可带 `needs:[{role, note}]` 字段，你据此逐条定向派发给对应成员（相当于把成员的「待办留言」变成一条条直发消息）。你记录每次转发的 `role:from→to` 到 `RUN.log`，形成可审计的交接链。
+- **不要**：让 `send_message` 当正式下一轮审查/评审（邮件无门禁）；跨角色契约裁定必须过 lead。
+
+## 3. 阶段推进（persist 版流水线）
+
+仍按 clarify→design→implement→review→test→deliver 推进，只是每一步由你向对应成员 `send_message` 派活。**成员只把工件内容 report 回来，你（lead）收到后立即用 `write` 落盘对应工件**（这样工件成为你本轮产出文件，聊天框可点击预览）：
+
+1. 给 `pm` 成员派 clarify，等其 report `specMarkdown/planSkeleton/tasks` → 你落盘 SPEC.md / PLAN.md 骨架 / TASKS.json。
+2. 给 `architect` 成员派 design，等其 report `designMarkdown/tasks` → 你落盘 PLAN.md 设计段 / TASKS.json 细化。
+3. 给 `backend`/`frontend` 成员**同时**派 implement（并行），等其 report 各任务 status → 你统一更新 TASKS.json。
+4. 给 `reviewer` 成员派 review，等其 report `reviewMarkdown` → 你落盘 REVIEW.md；需返工时只给受影响实现成员派 rework。
+5. 给 `qa` 派 test，等其 report `testMarkdown` → 你落盘 TEST.md。
+6. 你亲自 deliver：汇总 + 最终校验 + 更新 STATE.json + 写 RETRO.md。
+
+## 4. 跨会话恢复
+
+- 成员是可继续子 agent，会话持久化后仍可恢复；`/team resume <run>` 会再次把你唤起，并让你读 `team/<run>/` 与 `STATE.json`。
+- resume 时：读 `STATE.json.phase` 与 `ROSTER.json.members`；若成员 `ready`（仅存于存储），用 `send_message` 冷恢复它并从当前阶段继续；不要从头重跑。
+- 每次阶段推进都写 `STATE.json`，保证中断后能续。
+
+## 5. 收尾
+
+- deliver 完成后，`STATE.json.status = complete`；成员可保留（活团队）供继续指挥，也可不再理会（结算后自然停稳）。
+- 要彻底解散，可不再给成员派活；其会话仍是持久记录。
+
+## 6. 常驻团队模式（对齐 Qoder 的自动触发）
+
+persist 模式下，**本会话此后每条新消息都当作对本团队的输入**，不要当新对话。由 lead 判断分派：
+- **需求/新目标 → 先派 `researcher` 调研**（对齐「一有需求就触发调研员」），再进 clarify/design；
+- **修改/迭代意见 → 交给对应实现成员**（backend/frontend/补位）；
+- **评审/测试要求 → reviewer / qa**；
+- **简单提问/状态 → 直接回复**，或 `list_agents` 看成员的 running/idle/ready、用 `STATE.json` 摘要当前阶段与进度。
+- 成员可定向 `send_message`；跨角色契约裁定仍由 lead 仲裁。

package/skills/expert-team/references/PIPELINE.md

@@ -0,0 +1,58 @@
+# 阶段流水线与门控
+
+顺序固定，每阶段有门控。门控未过不得进入下一阶段；返工只回退到受影响的角色，不整队重来。
+
+| 阶段 | 执行者 | 输入 | 产出 | 门控（进入下一阶段的条件） |
+|---|---|---|---|---|
+| clarify | pm | TASK.md | SPEC.md（Ultra Spec）、PLAN.md 骨架、TASKS.json 初稿 | SPEC 验收标准逐条可测；安全边界三级权限写清；歧义已问或标为假设 |
+| research | researcher | SPEC、PLAN | RESEARCH.md（代码定位/依赖/环境/存量约束） | 相关文件与调用链、环境结论、存量约束已写清（纯新项目可跳过） |
+| design | architect(+dba 数据契约) | SPEC、RESEARCH、PLAN | PLAN.md「设计」段（接口 I/O 用 JSON Schema + 数据契约）、TASKS.json 细化 | **契约冻结到签名级**：字段/类型/错误语义/DML 明确且作为实现端只读基准；每任务有 owner+acceptance+dependsOn |
+| **spec-review** | reviewer + sec(+性能补位) | SPEC、PLAN | REVIEW-SPEC.md（对 Spec 的交叉审查） | Spec 缺陷已修；验证者反向推导剔除幻觉误报 |
+| **方案确认** | lead | SPEC、PLAN、TASKS | 中文「执行方案」汇总 + `ask_user_question` | 用户已确认「执行」；未确认不改代码、不进 implement |
+| implement | backend/frontend(+ui/dba 按需)，**按 DAG 并行** | PLAN 契约、TASKS.json、UI.md | 工作区代码改动、TASKS.json 状态更新 | 每任务 `verify` 命令通过 + `changedPaths` 落在 `inScope` 内 + acceptance 证据齐；无未解决 blocker/choices |
+| review | reviewer | SPEC、PLAN、代码 diff、最新 attempt | REVIEW.md + TASKS.json verdict | `verdict=pass` 才 `completed`；`needs_revision/reject` 必须 `failed` 且带 ≥1 finding；lead 自动开 `repair-N` + `review-N+1` |
+| test | qa(+ui验证补位) | 代码 + 验收标准 | TEST.md（含证据） | **TDD 自愈闭环**：qa 先自动生成用例→运行；失败项自动新建 `repair-N`（kind=`verification`，依赖指向对应实现）→ 实现角色修复 → 重跑，直到通过或 `maxTestRounds`（默认 3），到顶升级用户；测试失败不得当通过 |
+| deliver | lead | 全部工件 + 代码 | TASK.md 交付结论、STATE.json=complete、RETRO.md、LEARNINGS 追加 | 最终校验通过 + 无未关 blocker；到 `maxReviewRounds` 仍非 pass 的项已升级 |
+
+## 门控判定原则
+
+- **clarify**：任何会让开发/验收产生歧义的点，pm 必须 `ask_user_question`；拿不准就不进入 design。
+- **research**：涉及存量代码的任务先调研；调研员只读 + 只读环境检查，产出 RESEARCH.md，让 architect/实现者不盲写。
+- **design**：接口/DML 契约必须精确到 JSON Schema（字段/类型/错误语义）并**冻结为签名级基准**，实现端只读它——否则并行 backend/frontend 会产生字段/状态机交叉分歧（历史教训：曾一次返工 15 项）。涉及量表/迁移/报表的任务同时派 `dba` 出数据契约（PLAN.md 数据段），与接口契约双向核对后再冻结。
+- **spec-review（Spec 交叉审查）**：写代码前对 Spec 做多视角并行审查——架构师视角查模块边界/接口，reviewer 视角查正确性，`sec` 视角查权限/注入/敏感数据，性能补位视角查风险；再用「验证者反向推导」剔除幻觉误报。Spec 是最大杠杆，这里多花一点省后面几倍返工。
+- **方案确认（用户拍板，必须）**：spec-review 通过后，lead 用**中文**汇总成一份「执行方案」（范围/关键决策/任务清单/风险），`ask_user_question` 让用户选「执行」或「修改方案」。**未确认不得 implement**；用户要求修改 → 回 pm/architect 改 `SPEC/PLAN/TASKS` 再确认。这是防止「没确认就开工」的关键门控。
+- **implement**：按 `TASKS.json` 的 `dependsOn` 排成 **DAG 顺序**派工（不是无脑并行）——无依赖的并行，有依赖的按序。共享工件（TASKS.json）由各实现者「只改自己的条目」更新，避免互踩；跨模块接口冲突由 lead 裁决。
+- **大工件安全返回**：不要把超大交付物（整份 schema、长设计文）塞进 one-shot workflow 的聚合返回——会被截断、丢失后段角色。改用子角色 `send_message` 单发，或拆成多个小 workflow；关键字段先确认非截断（历史教训：曾整段丢失 backend/frontend/reviewer/qa 与 architect 尾部）。
+- **契约只读并行**：implement 开始时，实现者先读冻结的 PLAN.md 契约；跨角色要改契约（字段/状态机）必须先提给 lead 仲裁，不得各自临时改——否则并行出分歧（历史教训）。
+- **模糊选择拍板**：实现中遇到「算法用哪个 / 兼容是降级还是报错」这类模糊选择，lead 抛候选项 `ask_user_question` 让用户拍板，不让 AI 闷头猜。
+- **review→rework**：reviewer 只读审代码（正确性/安全/性能/架构一致性），盯逻辑错误、别纠结样式；只把受影响任务标 `rework` 并重跑对应实现角色。
+- **test**：必须真实执行（bash），结果+证据写进 TEST.md，不凭推断；有 UI 的任务加 ui验证补位做端到端。
+- **deliver**：lead 亲自做最后一次构建/测试校验，写交付结论 + RETRO.md，把可复用经验追加进 LEARNINGS.md。
+
+## 回退规则
+
+- spec-review 发现 Spec 有误 → 回 clarify/design（pm/architect 改 Spec）。
+- implement 发现契约有误 → 不回退全队，写 blocker 交 lead 转 architect，只重定契约后重跑受影响实现者。
+- review 非 pass → 不重跑旧 review：lead 自动建 `repair-N`（依赖指向被审的实现任务，不依赖 failed 的 review）+ 新 `review-N+1`（针对最新 attempt），直到 pass 或 `maxReviewRounds`，到顶升级到用户。
+
+## 质量门禁与自动调度（机器可判定）
+
+“直到共识”不是“几个角色都说没问题”，而是下列**全部**满足（详见 `WORKSPACE.md`）：
+
+```
+所有必需门禁 pass + 所有 acceptance 通过 + 无 blocker/high finding
++ 最新 attempt 已被独立 reviewer 审查 + 声明的 verify 命令通过 + changedPaths 在 inScope 内
+```
+
+- **任务 kind 与合同**：`requirements / research / design / implementation / verification / review / repair / integration / work / quality`（**阶段即 kind**：research 阶段给 researcher 的调研任务写 `kind=research`，design 阶段给 architect 的设计任务写 `kind=design`；不要自造词表外的 kind——写了不阻断门禁，但会告警且该任务没有 kind 专属门禁）。实现/修复任务必须带 `objective/acceptance/inScope/verify`，才能建；没有合同的实现任务不要创建。
+- **状态机**：`pending → claimed → in_progress → completed | failed | cancelled`；`rework` 为 review 返工过渡态。依赖只认上游 `completed`，`failed/cancelled` 永不解锁下游。
+- **attempt/attemptId**：每次派工/转派递增 attempt、设新 attemptId；成员回报带当前 attemptId，旧 attemptId 的迟到写入一律拒绝；转派先使旧 attempt 失效。
+- **空闲自动领题**：persist 模式下，成员 idle 后自动领下一个依赖已满足的 `pending` 任务；一成员一次最多 1 个未完成任务；冷启动对残留开放 attempt 自动重试一次。
+- **自动修复链**：review 非 pass → `repair-N` + `review-N+1`（独立、针对最新 attempt），`round` 递增至 `maxReviewRounds`，到顶升级到用户，不无限互审。
+  - **轮次上限是代码强制，不是口号**（2026-09-11 起）：`maxReviewRounds` / `maxTestRounds` 落在 `lib/command.js` 的 `ROUND_LIMITS`（默认 3/3；`config.limits` 或 env `DSH_EXPERT_TEAM_MAX_REVIEW_ROUNDS` / `DSH_EXPERT_TEAM_MAX_TEST_ROUNDS` 可改）。四道机判：① 读侧 `/team check` 报 **`REWORK_LOOP_UNESCALATED`**（超过上限且无 `pendingDecision`）；② 读侧报 **`FINDING_REOPENED`**（同一 finding 连续两轮未闭环 ⇒ 判为**规格歧义**，应升级裁定而非再派修复）；③ 写侧**新建**超限质量任务且无 `pendingDecision` ⇒ **落盘前拒绝** `REWORK_LOOP_LIMIT`（fail loud，不静默截断）；④ METRICS 出「评审效率（轮次/撤销率）」。
+  - **到顶的正确动作是「升级用户」，不是「再来一轮」**——想继续必须先把 `pendingDecision` 立起来（用户点「继续」后再临时调高上限）。
+  - ⚠️ **诚实边界（不要高估写侧拦截）**：写侧 `REWORK_LOOP_LIMIT` 只挡**经插件路由**的写入，且实际可达的只有 **`/plan/approve`** 一处（`/plan` 因 `normalizeDraft` 钉死 `round:1` 而不可达；面板的任务路由只按 id 改既有任务、无新增面，故不需要守卫）。**lead 用 `write`/`edit` 直接改 `TASKS.json` 会完全绕过它**（那是文件工具，不经过插件）——而"lead 自己回写 TASKS.json"恰恰是本 skill 要求的常规动作。⇒ **真正的强制点是读侧**：`checkTasks` 在**每次 `/state` 轮询**与 `/team check` 都会重算违规并推到浮层红条，绕不过去。另：`POST /plan` 因 `normalizeDraft` 把 `round` 钉死为 1，**本来就造不出**超限任务（该路由不可达属预期，不是漏洞）。
+  - 收敛口径：只有 **P1/P2 + 可机判项**阻塞 `pass`；**P3/文字项不阻塞**（进 backlog）；`verify` 未实跑不得计 pass。
+- **coverage matrix**：design 阶段把用户每个显式约束映射到 ≥1 条任务并在 PLAN/看板锁定。
+- **reviewer 守界**：只读；不给修复任务标 pass；不审自己刚写的实现/修复。
+- **完成时越界审计**：实现者回报 `changedPaths`，lead 对照 `inScope`，越界不得标 `completed`。