@rowansenne/workflow-run 0.36.0 → 0.36.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,12 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.36.1] - 2026-11-18
8
+
9
+ ### 优化
10
+
11
+ - `/dev` 的 M / L 需求与方案先讨论草稿,用户确认后再发起适用的独立审核。复审聚焦变更、待关闭的阻塞项和受影响的验收项。可选建议不阻塞收尾,已有答复覆盖的决定直接用于登记当前版本的确认。
12
+
7
13
  ## [0.36.0] - 2026-11-17
8
14
 
9
15
  ### 新增
package/dev/SKILL.md.tpl CHANGED
@@ -21,7 +21,7 @@ description: "Explicitly requested dev workflow for feature development or bug f
21
21
  - 生成澄清清单、需求、方案和交付说明时,按 `<skills>/workflow/references/templates.md`「文档模板的两部分」读取生效模板。遵守要求区,只用内容区生成正文。无标记的模板沿用旧格式,边界有误时先修复。
22
22
  - 先确定工作分支、已有改动的归属与需求名;切分支重新查询绑定,不替用户丢弃已有改动。
23
23
  - 规模由 agent 判定并说明,不询问规模确认;M / L 的需求理解和方案须用户确认后再实现,权限 / 资金至少按 M。
24
- - 新建 M / L 完整运行(`document_review_policy: 1`)的需求与方案草稿在各自收尾前须经独立子 agent 审查。按 [execution.md 的文档审查](../workflow/references/execution.md#需求与方案审查) 交接;子 agent 不可用时等用户决定是否允许本次自查。S 和升级前已有运行沿用原门禁。
24
+ - M / L 先和用户讨论、确认需求与方案草稿,收到明确反馈直接改稿。启用 `document_review_policy: 1` 的运行各自在确认后做独立审查,按 [文档审查流程](../workflow/references/execution.md#需求与方案审查) 处理阻塞项与差异复核;需要新的取舍才请用户决定。子 agent 不可用时等用户决定是否允许本次自查。
25
25
  - F2 先落偏业务场景的 clarification.md,供用户找产品核对;逐轮更新原问题状态、追加新问题和反馈。业务明确并完成现状调研后,再进入 F3 澄清技术约束;最终需求确认后进入 F4。
26
26
  - S 快速通道须用户明确同意,且 ≤3 文件、无配置 / SQL / 对外接口 / 表结构 / 权限 / 资金变更,且没有 F2 / F3 已确认的业务决定、本次未发布正式清单且未创建完整流程运行;已有清单或运行沿用完整流程,具体资格见 F4。
27
27
  - 快速通道仍编译、测试、当前会话审查,但不 bind、不建运行、不落需求 / 方案 / 审查 / 交付文档;超限或用户要求落盘先停,回 F3(bug 回 B3)补需求文档,再进入方案。
@@ -54,11 +54,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
54
54
 
55
55
  ### F3 — 需求澄清(偏技术约束)
56
56
 
57
- 读 [clarify.md 的 F3](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);基于已确认业务场景,查清可行性、接口兼容、数据与一致性、权限、依赖及验证条件。事实自己查,需用户取舍的技术约束给推荐并等答复;详细设计留到 F4。发现新业务问题回 F2 更新清单找产品确认。全部明确后,完整流程按文档门禁审查需求草稿,再确认、收尾 requirement.md、完成 F3,进入 F4。
57
+ 读 [clarify.md 的 F3](references/clarify.md) 与 [planning.md 的 F3](references/planning.md);基于已确认业务场景,查清可行性、接口兼容、数据与一致性、权限、依赖及验证条件。事实自己查,需用户取舍的技术约束给推荐并等答复;详细设计留到 F4。发现新业务问题回 F2 更新清单找产品确认。完整流程先确认需求草稿,再完成适用的审查、收尾 requirement.md 并完成 F3,进入 F4。
58
58
 
59
59
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
60
60
 
61
- 读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求起草方案,按文档门禁审查草稿,再用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;涉及 HTTP 接口或接口行为变化时列出接口、AC、测试场景及命令 / 环境。S / M 简版、L 完整版,M / L 确认后记录 approval,再进入实现。
61
+ 读 [planning.md 的 F4](references/planning.md),复用 F3 已选通道;完整流程基于已收尾需求起草方案,按文档门禁先确认、再完成适用的审查,用 `artifact.mjs finalize --kind plan` 收尾 `plan.md`。方案引用需求文档及版本,只写实现设计、实施与验证计划;涉及 HTTP 接口或接口行为变化时列出接口、AC、测试场景及命令 / 环境。S / M 简版、L 完整版,M / L 在收尾后记录当前版本的 approval,再进入实现。
62
62
 
63
63
  ### F5 — 实现
64
64
 
@@ -88,11 +88,11 @@ description: "Explicitly requested dev workflow for feature development or bug f
88
88
 
89
89
  ### B3 — 定位根因
90
90
 
91
- 读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程按文档门禁审查需求草稿并收尾 requirement.md、完成 B3,再进入修复方案。
91
+ 读 [bug.md 的 B3](references/bug.md);定位根因、形成证据并查同类风险。收尾时判定通道,完整流程先确认需求草稿,再完成适用的审查、收尾 requirement.md 并完成 B3,进入修复方案。
92
92
 
93
93
  ### B4 — 修复与验证
94
94
 
95
- 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程在原方案草稿追加修复方案、更新文档头,按文档门禁审查后用 `artifact.mjs finalize --kind plan` 收尾;M / L 确认后记录 approval、implement 再修复,复现测试由红变绿。
95
+ 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程在原方案草稿追加修复方案、更新文档头,按文档门禁先确认、再完成适用的审查,用 `artifact.mjs finalize --kind plan` 收尾。M / L 收尾后记录当前版本的 approval,再记录 implement 并修复,复现测试由红变绿。
96
96
 
97
97
  ### B5 — 审查与交付
98
98
 
@@ -18,12 +18,12 @@
18
18
  - 区分根因与症状:只在出错表象处加判空 / try-catch 不算修复,除非能说明那里就是根因。
19
19
  - 检查同一根因是否在其他调用方同样存在。
20
20
  - 预期业务行为还需产品确认时,按 clarify.md 的清单规则在 B3 初判规模、bind、start,逐轮发布同目录的 clarification.md 并保存等待反馈;需求明确后沿用该运行收尾需求文档。
21
- - 根因与修复目标明确后,按 F4 的标准判定规模与快速通道;完整流程在 B3 收尾前 bind、start,按需求模板将现象、期望、范围、验收与澄清决定写成草稿,按 `clarify.md` 的 F3 审查适用草稿并完成需求理解确认,用 `artifact.mjs finalize --kind requirement` 收尾并标 B3 completed,再进 B4。根因证据作事实依据,修复方式留在 plan.md;已有文档先核对后在草稿更新,不自动覆盖原需求。
21
+ - 根因与修复目标明确后,按 F4 的标准判定规模与快速通道;完整流程在 B3 收尾前 bind、start,按需求模板将现象、期望、范围、验收与澄清决定写成草稿,按 `clarify.md` 的 F3 先讨论并确认草稿,再完成适用的审查,用 `artifact.mjs finalize --kind requirement` 收尾并标 B3 completed,再进 B4。根因证据作事实依据,修复方式留在 plan.md;已有文档先核对后在草稿更新,不自动覆盖原需求。
22
22
 
23
23
  ### B4 — 修复与验证
24
24
 
25
25
  - 复用 B3 收尾时按 F4 标准判定的规模和通道,不重复询问;范围变化时重新判定。快速通道退出时先回 B3 补需求文档,再补方案。
26
- - **完整流程先把修复方案追加进 `plan.md`**:沿用 B3 已绑定的需求与 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支、本次日期以及 requirement.md 的 cite / 版本。没有方案则按模板创建草稿,只填适用节。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」完成适用审查,再用 `artifact.mjs finalize --kind plan` 自检、归档旧版、发布并更新索引,不直接覆盖正式文件;输出的 previous 用于历史对照。运行 `artifacts.mjs --branch <当前修复分支>` 确认 latest.plan。M / L 取得用户确认后记录 approval,再 save implement: true;S 省 approval,仍须 implement。具体 JSON 和证据协议见 `<skills>/workflow/references/execution.md`。规模变化时说明依据、按新规模继续。
26
+ - **完整流程先把修复方案追加进 `plan.md`**:沿用 B3 已绑定的需求与 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支、本次日期以及 requirement.md 的 cite / 版本。没有方案则按模板创建草稿,只填适用节。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」先讨论草稿,M / L 用户确认后完成适用的审查,再用 `artifact.mjs finalize --kind plan` 自检、归档旧版、发布并更新索引,不直接覆盖正式文件;输出的 previous 用于历史对照。运行 `artifacts.mjs --branch <当前修复分支>` 确认 latest.plan。M / L 收尾后记录当前版本的 approval,再 save implement: true;S 省 approval,仍须 implement。具体 JSON 和证据协议见 `<skills>/workflow/references/execution.md`。规模变化时说明依据、按新规模继续。
27
27
  - 做能消除根因的**最小改动**;B2 的测试由红变绿,相关已有测试保持通过(运行方式同 F6)。
28
28
  - 如果历史脏数据需要修正,写成 SQL 脚本交给用户,不直接执行。
29
29
 
@@ -35,7 +35,7 @@ F1 形成初版需求理解后,在 F2、进入 F3 之前先输出清单,不
35
35
  - 依赖前置答案的问题也记录,注明「待 Qx 确认后讨论」。每轮突出当前能确认的问题,控制在 7 个以内;用户说「按推荐来」只确认本轮已经给出的推荐。
36
36
  - 用户带回答复或新版 PRD 后,恢复同一运行,从正式清单复制 tmp 草稿,更新原问题的答复和状态、追加新问题;反馈记录按轮追加。产品改口时保留原答复与变更原因。
37
37
  - 每轮汇总「已确认 / 仍待确认 / 本轮新增」,给出 PRD 的业务规则、场景、范围和验收调整建议;只在用户要求修改 PRD 时改原文。
38
- - 更新后再次 finalize,旧版自动归档,输出新版链接。内容变化会撤销本轮旧需求和方案凭据及下游确认,保留旧文件;后续须重新收尾需求与方案,M / L 重新确认方案。仍有未定业务项时继续留在 F2;「继续」或已修改 PRD 不代表未回答的问题自动确认。
38
+ - 更新后再次 finalize,旧版自动归档,输出新版链接。内容变化会撤销本轮旧需求和方案凭据及下游确认,保留旧文件;后续须重新收尾需求与方案,M / L 按文档审查流程核对并记录当前版本的方案确认。仍有未定业务项时继续留在 F2;「继续」或已修改 PRD 不代表未回答的问题自动确认。
39
39
  - 新会话明确继续时,读清单、最新 PRD 和运行 context,从未解决项继续,不重问仍有效的已确认项。
40
40
 
41
41
  业务项均已回答或由用户明确移出范围后,将清单标为「业务已明确」并 finalize。结合核对后的场景完成 F2 的代码与数据调研,再 save F2 completed、进入 F3。这里不提前生成 requirement.md,也不把业务反馈视为技术约束已确认。
@@ -56,6 +56,6 @@ F1 形成初版需求理解后,在 F2、进入 F3 之前先输出清单,不
56
56
 
57
57
  技术调研发现新的业务决定或场景冲突时,回 F2 更新业务清单并等待产品确认;确认后重查受影响的技术事实,再回 F3。已确认且不受影响的场景不重复问。bug 在 B3 内更新清单后继续技术澄清。
58
58
 
59
- 业务场景与技术约束都明确后,汇总需求目标、范围、验收标准、已确认决定和必要技术约束。沿用已有运行、复核规模(无需清单时在此判定通道,完整流程 bind、start)。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」核对适用的需求草稿。M / L 等用户确认理解一致,已有答复能覆盖最终草稿时可直接复用。用 `artifact.mjs finalize --kind requirement` 收尾并完成 F3 / B3,再进入 F4 / B4。
59
+ 业务场景与技术约束都明确后,汇总需求目标、范围、验收标准、已确认决定和必要技术约束。沿用已有运行、复核规模(无需清单时在此判定通道,完整流程 bind、start)。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」先给用户看草稿,直接落实明确反馈;M / L 在用户确认后送审,已有答复覆盖的决定可直接复用。用 `artifact.mjs finalize --kind requirement` 收尾并完成 F3 / B3,再进入 F4 / B4。
60
60
 
61
61
  requirement.md 是最终需求事实来源,引用清单 cite 与版本,只汇总有效场景、决定与约束;清单保留业务往返核对过程,plan.md 保存实现设计。值得长期记住的规则与取舍在交付时作为 DocNexus 沉淀候选。
@@ -26,9 +26,9 @@
26
26
  | 只有一两个技术取舍 | 给推荐和依据,能一轮确认就一轮结束 |
27
27
  | M / L 规模,或用户要求先把需求问清楚 | 逐轮确认约束,汇总需求、AC、不做什么与决定,等用户确认理解一致再进 F4 |
28
28
 
29
- **F3 的正式产物**:业务与技术约束均明确后,沿用已有绑定和运行、复核规模;没有清单时,完整流程在此 bind、start(stage F3,仅补记实际完成的 Step0、F1、F2)。用 `resolve.mjs template dev requirement-template.md` 读取模板,将目标、范围、AC、当前有效业务决定与必要技术约束写成草稿,在依据中引用业务清单 cite 与版本。按 `clarify.md` 的 F3 审查草稿、确认后,通过 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 并将 F3 标 completed,再进入 F4。不因清单发布或产品给了业务答复就跳过技术澄清。
29
+ **F3 的正式产物**:业务与技术约束均明确后,沿用已有绑定和运行、复核规模;没有清单时,完整流程在此 bind、start(stage F3,仅补记实际完成的 Step0、F1、F2)。用 `resolve.mjs template dev requirement-template.md` 读取模板,将目标、范围、AC、当前有效业务决定与必要技术约束写成草稿,在依据中引用业务清单 cite 与版本。按 `clarify.md` 的 F3 先讨论并确认草稿,再完成适用的审查,通过 `artifact.mjs finalize --kind requirement` 收尾 requirement.md 并将 F3 标 completed,再进入 F4。不因清单发布或产品给了业务答复就跳过技术澄清。
30
30
 
31
- requirement.md 是需求事实来源,context 只保存续接摘要。业务变化先回 F2 更新清单、复核现状,再到 F3 更新需求文档;仅技术约束变化回 F3;只调整实现设计则更新 F4 的方案。需求重新收尾后,更新依赖它的方案并重新确认 / 验证。历史需求不自动从旧 plan.md 拆出正文;恢复旧运行时先核实并补齐需求文档。
31
+ requirement.md 是需求事实来源,context 只保存续接摘要。业务变化先回 F2 更新清单、复核现状,再到 F3 更新需求文档;仅技术约束变化回 F3;只调整实现设计则更新 F4 的方案。需求重新收尾后,更新依赖它的方案,只确认受影响且尚未决定的取舍,再按当前版本登记确认和验证。历史需求不自动从旧 plan.md 拆出正文;恢复旧运行时先核实并补齐需求文档。
32
32
 
33
33
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
34
34
 
@@ -46,6 +46,6 @@ requirement.md 是需求事实来源,context 只保存续接摘要。业务变
46
46
 
47
47
  **S 规模快速通道(问用户)**:本次已发布正式清单或已创建完整流程运行时,直接沿用完整流程,不再询问快速通道;后续规模降为 S 也不切换。判定为 S 规模,且改动**不涉及**配置项、SQL / DDL、对外接口(HTTP 接口签名、MQ 消息体、对外 DTO)、表结构、权限、资金,也没有 F2 / F3 中确认过的业务决定,且本次尚未发布正式清单、尚未创建完整流程运行时,**明确询问用户是否走快速通道**:说明走快速通道时 F5~F6 照常(编译、测试都不省),审查按 F7 的快速通道说明在当前会话做,但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写(运行反馈仍照常记一行),F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续:明确同意才走快速通道;拒绝或答复没有明确同意,就按完整流程落盘交付(F3 需求 → F4 方案 → F7 审查 → F8 交付)。** 实现中一旦碰到上面任何一项、改动超过 3 个文件,或用户要求落盘 → 退出快速通道:先停下后续实现,重新评估并说明规模,按 Artifact Location 绑定需求,先回 F3(缺陷回 B3)补写并 finalize requirement.md,再到 F4 / B4 补方案;M / L 等用户确认方案后再继续,S 按简版方案推进。之后回 F5 完成实现、F6 验证、F7 审查并生成 `review.md`,交报告后等待用户选择交付,不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问,不省审查。
48
48
 
49
- **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。草稿按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」完成适用审查,再用 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 等用户确认并 save approval 后再进入 F5,S 无需 approval(方案按简版写)。尚未创建本次完整流程运行、且符合快速通道全部条件的 S,按上文询问一次;已经发布清单或创建运行的 S 直接落简版方案,不重复询问快速通道。
49
+ **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。按 `<skills>/workflow/references/execution.md` 的「需求与方案审查」先讨论草稿,M / L 用户确认后完成适用的审查。用 `artifact.mjs finalize --kind plan` 自检、归档并登记 F4;M / L 收尾后 save 当前版本的 approval,再进入 F5,S 无需 approval(方案按简版写)。尚未创建本次完整流程运行、且符合快速通道全部条件的 S,按上文询问一次;已经发布清单或创建运行的 S 直接落简版方案,不重复询问快速通道。
50
50
 
51
51
  **HTTP 接口验证计划**:涉及新增 / 修改 HTTP 接口,或参数校验、鉴权、状态码、响应结构及接口业务行为变化时,在验证计划列出方法、路径、关联 AC 与待测场景:正常请求、参数错误(有入参约束时),以及适用的未登录 / 无权限场景。沿用现有框架,明确已有用例如何复用、哪些需要补充、执行命令和环境;F6 按计划编写并执行。纯内部重构且接口行为不变、已有覆盖充分时只列现有测试,不另建重复用例。缺陷修复在 B4 使用相同规则。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rowansenne/workflow-run",
3
- "version": "0.36.0",
3
+ "version": "0.36.1",
4
4
  "description": "项目级 Agent Skills 一键初始化:workflow / dev / project-review / code-graph / database-query / nacos-config / md-to-wiki / 需求文档与技术上线方案生成",
5
5
  "keywords": [
6
6
  "agent-skills",
@@ -82,6 +82,7 @@ export function createDocumentHandoff(root, { branch, id, kind, text }) {
82
82
  inputs,
83
83
  draft: { text: draft.text, hash: draftHash },
84
84
  basis: basis ? { path: basis.path, hash: basis.hash, version: basis.version, text: basisText } : null,
85
+ rules: '按已确认的范围、验收项和技术约束审查。阻塞项须给出具体约束或验收依据及实际影响。架构偏好、可选优化和新增功能作为建议。需要新取舍时说明冲突,交用户决定。复审优先看基线差异、待关闭阻塞项和受影响的验收项;影响不明时扩大范围。',
85
86
  result_schema: {
86
87
  run_id: id,
87
88
  inputs,
@@ -30,35 +30,37 @@ plan.md 头部引用需求文档 cite 与版本,只写实现设计、技术风
30
30
  node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind plan --draft workflow-run/tmp/plan.md --input workflow-run/tmp/checkpoint.json
31
31
  ```
32
32
 
33
- 功能方案收尾的 checkpoint 可写 `{"steps":{"F4":{"status":"completed"}}}`;M / L 等用户确认时可同时写 waiting_user 和 waiting_for。bug 的 B4 还包含实现、验证,方案收尾时不能标完成,checkpoint 可省略。已有方案在草稿中保留正文并追加修复方案,更新当前分支和日期。
33
+ 功能方案收尾的 checkpoint 可写 `{"steps":{"F4":{"status":"completed"}}}`。bug 的 B4 还包含实现、验证,方案收尾时不能标完成,checkpoint 可省略。已有方案在草稿中保留正文并追加修复方案,更新当前分支和日期。
34
34
 
35
- M / L 取得用户实际确认后,用 save 记录 `approval: {"confirmed":true}`,程序绑定当前 plan.md 的 hash/版本;方案变更后旧确认失效。S 完整流程仍须收尾方案,但无需该确认记录。进入实现:
35
+ M / L 先取得用户对方案草稿的实际确认,正式收尾后用 save 记录 `approval: {"confirmed":true}`,程序绑定当前 plan.md 的 hash/版本。审核后的定稿仍在用户确认的范围、行为、技术取舍和风险边界内时,按原答复登记,发一条审查和修改摘要即可。已收尾方案更新后旧凭据失效,须按当前版本重新登记。S 完整流程仍须收尾方案,但无需该确认记录。进入实现:
36
36
 
37
37
  - feature:save `{"stage":"F5","status":"running","approval":{"confirmed":true}}`(S 可省 approval)。
38
38
  - bug:在 B4 save `{"status":"running","approval":{"confirmed":true},"implement":true}`;之后才改代码。
39
39
 
40
40
  未收尾方案、M / L 未确认、核心步骤 skipped 都会被拒绝。程序校验确认记录与版本,不能替代 agent 核实用户是否真的授权。
41
41
 
42
- 业务清单内容变化时撤销本轮 requirement / plan 凭据,清除旧方案确认、实现、验证、审查与交付选择,并重置后续步骤;正式文件和历史版本保留供查阅,相同清单内容重新发布不触发该失效处理。即便需求和方案正文不变,也必须分别重新 finalize,M / L 重新取得方案确认。
42
+ 业务清单内容变化时撤销本轮 requirement / plan 凭据,清除旧方案确认、实现、验证、审查与交付选择,并重置后续步骤;正式文件和历史版本保留供查阅,相同清单内容重新发布不触发该失效处理。即便需求和方案正文不变,也必须分别重新 finalize;M / L 在新方案上核对用户确认的决定是否仍适用,并重新登记当前版本的确认。
43
43
 
44
- 需求变化回 F3(bug 回 B3)重新澄清并 finalize requirement;程序清除旧方案确认、实现、验证、审查和交付选择,旧方案不能作为新需求的依据。即使方案正文不变,也要在 F4 / B4 重新收尾以绑定新需求版本;M / L 重新取得方案确认。只改实现方式则仅更新 plan,不改 requirement。手动改需求正文而未收尾也会使后续证据校验失败。
44
+ 需求变化回 F3(bug 回 B3),只澄清变化和受影响的内容,再 finalize requirement;程序清除旧方案确认、实现、验证、审查和交付选择。即使方案正文不变,也要在 F4 / B4 重新收尾以绑定新需求版本。M / L 只向用户确认新增或改变且尚未决定的取舍。只改实现方式则仅更新 plan。手动改需求正文而未收尾也会使后续证据校验失败。
45
45
 
46
46
  ## 需求与方案审查
47
47
 
48
- 运行记录有 `document_review_policy: 1` 且当前规模为 M / L 时执行。S 和没有该字段的升级前运行沿用原流程。新运行从 S 升为 M / L 后,如已有未审查的需求或方案,回对应阶段补审。需求在 F3 / B3 审查并完成用户理解确认后收尾;方案在 F4 / B4 审查后收尾,沿用现有方案确认,再开始实现。
48
+ M / L 在 F3 / B3 确认需求草稿,在 F4 / B4 确认方案草稿。运行有 `document_review_policy: 1` 时,两份文档各自在确认后做独立审查,再正式收尾。S 和没有该字段的升级前运行无需新增独立文档审查。新运行从 S 升为 M / L 后,如已有未审查的需求或方案,回对应阶段补审。
49
49
 
50
- 1. 草稿写到 tmp 后生成交接。需求用 `--kind requirement`,方案用 `--kind plan`。交接记录将要收尾的草稿正文及已登记的业务澄清或需求依据。
50
+ 1. **先讨论草稿。** 草稿写到 tmp,给用户草稿链接或重点摘要。收到明确修改意见就直接更新,回复改了哪些内容。只询问真正未决的取舍;继续讨论期间不生成独立审查交接、不收尾。已有明确答复覆盖的范围、行为和技术决定直接复用;单条修改意见只确认该项,仍需确认的内容集中在同一轮。需要等待时按 [runs.md](runs.md#写-checkpoint) 保存草稿路径、已确认决定及待答问题。
51
+ 2. **确认后送审。** 用户已确认本阶段草稿的决定后,将等待中的运行恢复为 `running`,按需生成交接。交接记录当前草稿正文及已登记的业务澄清或需求依据。
51
52
 
52
53
  ```sh
53
54
  node <skills>/workflow/scripts/review-handoff.mjs --id <id> --kind <requirement|plan> --draft <草稿.md>
54
55
  ```
55
56
 
56
- 2. 将输出的交接 `path` 及相关原始材料交给未参与起草的子 agent。要求它阅读交接里的草稿和依据正文,按需核对原始需求、已确认决定或相关代码。省去主 agent 的自评和预设发现。子 agent 只审查,按 `packet.result_schema` 返回结论、位置、依据、影响和阻塞标记。
57
+ 3. **审查按已确认的决定开展。** 把交接 `path`、适用的原始材料及用户决定的来源交给未参与起草的子 agent。审查者按 `packet.result_schema` 返回结论、位置、依据、影响和阻塞标记。
57
58
  - 需求审查核对范围、场景、规则、技术约束和可验证的验收标准。缺陷修复还要核对现象、根因证据和预期行为。
58
59
  - 方案审查以交接中的已定稿需求为依据,核对各验收项的实现与验证安排,以及适用的兼容性、权限、数据和回滚风险。
59
- 3. 主 agent 修订阻塞项,业务取舍交给用户或产品定。草稿或依据变化后重新生成交接,由独立审查者复核阻塞项及受影响内容,返回对应最终草稿的结论。一般建议按实际情况采纳或说明取舍。在交付给用户确认时附审查结论及阻塞项处理结果。
60
- 4. 子 agent 不可用时停在本阶段,记录 `waiting_user`,让用户选择等待独立审查或允许本次自查。只有明确同意后才自查,结果写 `mode: "self"`、实际审查者和 `fallback: {"confirmed":true,"reason":"无法派出子 agent 的实际原因"}`。独立审查结果写 `mode: "independent"` 和实际子 agent 标识。程序校验记录及文档内容,实际派遣和用户同意由主 agent 如实记录。
61
- 5. 将最终结果保存为 tmp 下的 JSON。执行本阶段的 `artifact.mjs finalize` 时额外传 `--packet <交接JSON路径> --result <结果JSON路径>`。收尾会拒绝缺失、过期或仍有阻塞项的结果。通过后审查证据随需求或方案版本写入本次运行的产物记录;F7 / B5 的代码审查仍按下文执行。
60
+ - 阻塞项的 `evidence` 指向具体的验收项、已确认决定或可查证的约束,`impact` 写明实际冲突、不可验证的验收项或会引入的风险。架构偏好、可选优化和新增功能填 `blocking: false`,按需采纳或关闭。如果建议被误标为阻塞,主 agent 提供对应的范围或决定,请审查者核实并更正结论。审查者发现需要改变用户决定的真实冲突时,写明影响,由用户或产品决定取舍。
61
+ 4. **修订后复核差异。** 在既定决定内直接修复;如有新取舍,一次说明受影响的范围和建议,等待答复后修改。草稿或依据变化时生成绑定当前版本的新 packet。将上一轮同一文档的 packet 和结果(若基线是已收尾版本,也可用该版本正文、依据和审查记录)、正文及依据的差异、待关闭阻塞项和受影响的 AC 或章节一起交给审查者。优先复用原审查者,复核这些内容和相邻约束;基线缺失或无法界定影响时扩大范围。新结果使用当前 packet 的 `inputs`,在 `summary` 注明基线、复核范围及关闭的阻塞项;`findings` 如实保留仍适用的发现。
62
+ 5. **需要降级时取得授权。** 子 agent 不可用时在当前阶段保存 `waiting_user`,让用户选择等待独立审查或允许本次自查。只有明确同意后才自查,结果写 `mode: "self"`、实际审查者和 `fallback: {"confirmed":true,"reason":"无法派出子 agent 的实际原因"}`。独立审查结果写 `mode: "independent"` 和实际子 agent 标识。程序校验记录及文档内容,实际派遣和用户答复由主 agent 如实记录。
63
+ 6. **审核通过后收尾。** 将最终结果保存为 tmp 下的 JSON。执行 `artifact.mjs finalize` 时额外传 `--packet <交接JSON路径> --result <结果JSON路径>`。收尾会拒绝缺失、过期或仍有阻塞项的结果。审查后未引入用户尚未决定的新取舍时,用已有答复收尾;方案正式收尾后再记录当前版本的 `approval`。F7 / B5 的代码审查按下文执行。
62
64
 
63
65
  ## 验证证据
64
66
 
@@ -85,7 +85,7 @@ F3 / B3 只能在需求文档 finalize 后完成;requirement.md 是需求事
85
85
 
86
86
  - 用户选修复:save `stage: F5`、`status: running`、`decision: {"action":"fix","confirmed":true}`;bug 回 B4。回到前面的阶段会自动重置该阶段及后续的完成标记、清除旧交付选择,旧 checkpoint 保留在 history;修复、验证和复审后再次等待选择。业务场景变化先回 F2 更新清单,再到 F3 重新收尾需求;仅技术约束变化回 F3,规模变化同时写 size。
87
87
  - 用户明确选交付:按 execution.md 核对本轮证据,save `stage: F8`、`status: running`、`decision: {"action":"deliver","confirmed":true}`;bug 留在 B5。只记录用户实际确认的选择,遗留风险写 context。
88
- - 等方案确认:`status: waiting_user`,waiting_for 说明待确认方案;方案已写不代表用户已同意。
88
+ - 等需求/方案草稿反馈:`status: waiting_user`,waiting_for 说明待答问题,context 保存 tmp 草稿路径、已确认决定及待确认项。恢复时先核对草稿是否仍对应这些决定,直接落实明确反馈。待决定项解决后按 [execution.md](execution.md#需求与方案审查) 送审和收尾。
89
89
  - 环境等阻塞:`status: blocked`、reason 说明原因,保留步骤与 remaining;解除后 save running。
90
90
  - 取消:用 cancel,input 提供 reason,不能用 complete 把取消记成完成。
91
91