@rowansenne/workflow-run 0.27.0 → 0.28.0

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.
Files changed (35) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +9 -1
  3. package/create-release-md-doc/SKILL.md.tpl +3 -5
  4. package/create-tech-md-doc/SKILL.md.tpl +3 -5
  5. package/dev/SKILL.md.tpl +8 -8
  6. package/dev/references/bug.md +3 -1
  7. package/dev/references/delivery-template.md +1 -1
  8. package/dev/references/delivery.md +9 -7
  9. package/dev/references/implementation.md +4 -0
  10. package/dev/references/plan-template.md +1 -1
  11. package/dev/references/planning.md +2 -2
  12. package/dev/references/preflight.md +2 -2
  13. package/package.json +1 -1
  14. package/project-review/SKILL.md.tpl +3 -3
  15. package/project-review/references/reporting.md +8 -8
  16. package/workflow/SKILL.md.tpl +1 -0
  17. package/workflow/lib/artifact-finalize.mjs +144 -0
  18. package/workflow/lib/code-snapshot.mjs +55 -0
  19. package/workflow/lib/meta-store.mjs +4 -2
  20. package/workflow/lib/path-match.mjs +21 -0
  21. package/workflow/lib/requirements.mjs +12 -7
  22. package/workflow/lib/run-gates.mjs +136 -0
  23. package/workflow/lib/runs.mjs +56 -12
  24. package/workflow/lib/workspace-read.mjs +3 -1
  25. package/workflow/references/architecture.md +10 -0
  26. package/workflow/references/capabilities.md +1 -1
  27. package/workflow/references/execution.md +95 -0
  28. package/workflow/references/requirements.md +12 -13
  29. package/workflow/references/runs.md +7 -5
  30. package/workflow/references/status.md +1 -0
  31. package/workflow/scripts/artifact.mjs +39 -0
  32. package/workflow/scripts/review-handoff.mjs +59 -0
  33. package/workflow/scripts/review-scope.mjs +2 -21
  34. package/workflow/scripts/run.mjs +6 -8
  35. package/workflow/scripts/view.mjs +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,14 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.28.0] - 2026-10-26
8
+
9
+ ### 变更
10
+ - 完整 dev 的关键转换加入程序门禁:方案确认绑定正文版本,进入实现、审查与交付须有对应证据,严重遗留风险须逐项明确接受。
11
+ - 验证和审查绑定执行前的 Git/工作区快照,交付选择绑定本轮报告 hash 和版本;代码、基线、需求事实或报告变化时拒绝复用旧证据。
12
+ - 新增 artifact finalize / resume / abort:知识模板检查后统一发布、归档、更新索引与运行证据;meta.json 保存中断待办,重试不重复升版本,原 wiki 页面记录自动保留。
13
+ - 新增 review-handoff,从已保存的需求事实、范围和验证结果生成交接 JSON;独立审查返回报告草稿、结构化问题与逐文件覆盖,由主 agent 收尾。快速通道和首次创建运行时机保持不变。
14
+
7
15
  ## [0.27.0] - 2026-10-24
8
16
 
9
17
  ### 变更
package/README.md CHANGED
@@ -620,9 +620,11 @@ workflow-run/docs/requirements/<需求名>/<项目名>/
620
620
  * **随代码提交和独立文档仓库两种用法的结构完全一样**,切换时文件不用挪。一个需求横跨多个服务时,各服务在同一个需求目录下各占一个 `<项目名>/`。项目名写在 `workflow/profile.json` 的 `artifacts.project`:随代码提交时不用配置,取 git 远端仓库名(没有远端用目录名),第一次落盘时自动写进去;独立文档仓库时由 `docs-repo` 配置。
621
621
  * 旧版本随代码提交时没有 `<项目名>/` 这一层;`upgrade` 会把这些需求目录里的文件迁到 `<需求>/<项目名>/`(被 git 跟踪的用 `git mv`,保留历史),结尾列出迁移了哪些需求,改动由你提交。目标里已有同名文件的需求不动,并提示手动处理;`doctor` 也会提示还没迁移的需求。
622
622
  * **需求名由你定**:dev 在 Step 0 先确定工作分支,再查询绑定并确认需求名,给不出名字或说不清这次要做什么时不会进入开发流程(默认值按分支名生成;也可以选已有的需求,例如修 bug 的新分支挂到原需求下)。从 `/workflow` 完整链路开始时同样先问(只问名字,第一次落盘时才 `bind`);S 快速通道也问,但不绑定、不落盘。确定后,同一分支上的各 skill 都写到这个目录,不再问。一个需求可以绑定多个分支。
623
- * 路径由 `workflow/scripts/requirement.mjs path <种类>` 给出,每种产物文件名固定,目录里只留最新版,引用不会失效;版本号记在 `meta.json` 的 `versions`。已有旧版时,上一版先复制到 `workflow-run/tmp/old-artifacts/<需求>/<项目>/<种类>_v<N>.md`(不提交),新版直接覆盖写入;skill 会列出归档的文件,请你确认后自己删除。上一版发布过 wiki 时,新版沿用同一个页面。
623
+ * 正式文档先写 tmp 草稿,再用 `artifact.mjs finalize` 自检、归档旧版、发布并更新索引与运行证据,输出 path / cite;文件名固定、目录只留最新版。中断后用 resume 恢复,重复命令不会重复升版本;旧版在 tmp/old-artifacts/,不替用户删除,wiki 页面记录自动沿用。底层 requirement path / sync 仍保留,新的正式流程统一走 finalize。
624
624
  * 需求目录写在项目根的 `.ignore` 里,ripgrep 和 agent 的代码搜索会跳过它,产物多了不会污染搜索结果(找历史决策用 DocNexus)。git 不受影响,建议随代码提交。
625
625
 
626
+ 完整 dev 的关键阶段由程序校验:M / L 方案确认绑定具体版本,测试证据和审查报告绑定包含未提交改动的代码快照,交付选择绑定本轮报告。相关代码、基线或报告变化后需重新验证/审查和选择。独立审查交接由脚本从需求事实、范围与验证结果生成;快速通道和首次创建运行的时机保持不变。协议见 [execution.md](workflow/references/execution.md)。
627
+
626
628
  **独立文档仓库(可选)**:不想让产物进代码仓库、或一个需求横跨多个服务时,装好 skills 后在项目根运行一条命令:
627
629
 
628
630
  ```bash
@@ -680,6 +682,10 @@ workflow-run(安装器仓库)/
680
682
  │ │ ├── requirement-read.mjs # 需求目录与元信息读取
681
683
  │ │ ├── requirements.mjs # 绑定、版本归档与索引同步
682
684
  │ │ ├── runs.mjs # 运行状态、阶段与完成校验
685
+ │ │ ├── run-gates.mjs # 方案、验证、审查与交付门禁
686
+ │ │ ├── code-snapshot.mjs # 代码内容摘要,绑定验证和审查证据
687
+ │ │ ├── artifact-finalize.mjs # 可恢复的产物收尾
688
+ │ │ ├── path-match.mjs # 共享范围匹配
683
689
  │ │ ├── meta-store.mjs # 写锁与原子存储
684
690
  │ │ ├── document-model.mjs # 标题、章节、表格等纯文本模型
685
691
  │ │ ├── artifact-model.mjs # 产物类型、元信息、审查与交付解析
@@ -693,6 +699,8 @@ workflow-run(安装器仓库)/
693
699
  │ ├── scripts/pr-desc.mjs # 按本分支产物生成 PR / MR 描述
694
700
  │ ├── scripts/template.mjs # 修改 / 创建模板:草稿 → 校验与影响 → 保存
695
701
  │ ├── scripts/tables.mjs # 找出改动涉及的数据库表
702
+ │ ├── scripts/artifact.mjs # 草稿收尾 / 中断恢复 / 安全取消
703
+ │ ├── scripts/review-handoff.mjs # 自动生成审查交接与结果结构
696
704
  │ ├── scripts/requirement.mjs # 产物按需求归档:绑定需求名、落盘路径、meta.json
697
705
  │ ├── scripts/view.mjs # 项目文档视图(本地静态页面)
698
706
  │ ├── scripts/make-template.mjs # 从样例文档抽模板骨架
@@ -71,11 +71,9 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
71
71
 
72
72
  ### Step 4 — 写文件
73
73
 
74
- - 路径:运行 `node <skills>/workflow/scripts/requirement.mjs path release --branch <dev分支>`,写到输出的 `path`(`workflow-run/docs/requirements/<需求名>/<项目名>/release-doc.md`,文件名固定;已有旧版时直接写新版,上一版由脚本归档到输出的 `previous`)。规则见 `<skills>/workflow/references/requirements.md`。
75
- - 退出码 2(这个分支还没绑定需求):问用户这个需求叫什么,默认值用输出的 `suggested_name`,再 `requirement.mjs bind --name "<需求名>" --branch <dev分支>`;用户不给名字时 `bind` 按分支名生成。
76
- - `wiki_record` 非空:上一版已发布到 wiki,新版第一行原样写这条记录,重新发布时更新同一页面。
77
- - 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`;输出里 `archived` 非空(上一版已归档到 `workflow-run/tmp/old-artifacts/`)时告诉用户归档了哪些文件,请用户确认不再需要后自己删除;输出里 `commit` 非空(独立文档仓库模式)时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物(「参考产物」等)写 `requirement.mjs path` 输出的 `cite`。
78
- - 写完运行 `node <skills>/workflow/scripts/lint-doc.mjs <文档路径> --skill create-release-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
74
+ - 正式收尾:Step 4 进入 L4,先写 `workflow-run/tmp/release-doc.md` 草稿,再用 `node <skills>/workflow/scripts/artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind release --draft <草稿> --branch <dev分支>` 自检、归档旧版、发布并更新索引/运行证据;使用返回的 path / cite,规则见 `<skills>/workflow/references/execution.md`。
75
+ - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
76
+ - 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-release-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
79
77
  - 再把路径和摘要告诉用户。
80
78
 
81
79
  ### Step 5 — 后续(都需要用户同意)
@@ -69,11 +69,9 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
69
69
 
70
70
  ### Step 4 — 写文件
71
71
 
72
- - 路径:运行 `node <skills>/workflow/scripts/requirement.mjs path tech --branch <dev分支>`,写到输出的 `path`(`workflow-run/docs/requirements/<需求名>/<项目名>/tech-doc.md`,文件名固定;已有旧版时直接写新版,上一版由脚本归档到输出的 `previous`)。规则见 `<skills>/workflow/references/requirements.md`。
73
- - 退出码 2(这个分支还没绑定需求):问用户这个需求叫什么,默认值用输出的 `suggested_name`,再 `requirement.mjs bind --name "<需求名>" --branch <dev分支>`;用户不给名字时 `bind` 按分支名生成。
74
- - `wiki_record` 非空:上一版已发布到 wiki,新版第一行原样写这条记录,重新发布时更新同一页面。
75
- - 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`;输出里 `archived` 非空(上一版已归档到 `workflow-run/tmp/old-artifacts/`)时告诉用户归档了哪些文件,请用户确认不再需要后自己删除;输出里 `commit` 非空(独立文档仓库模式)时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物(「参考产物」等)写 `requirement.mjs path` 输出的 `cite`。
76
- - 写完运行 `node <skills>/workflow/scripts/lint-doc.mjs <文档路径> --skill create-tech-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
72
+ - 正式收尾:Step 4 进入 T4,先写 `workflow-run/tmp/tech-doc.md` 草稿,再用 `node <skills>/workflow/scripts/artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind tech --draft <草稿> --branch <dev分支>` 自检、归档旧版、发布并更新索引/运行证据;使用返回的 path / cite,规则见 `<skills>/workflow/references/execution.md`。
73
+ - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
74
+ - 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-tech-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
77
75
  - 再把路径和摘要告诉用户。
78
76
 
79
77
  ### Step 5 — 后续(都需要用户同意)
package/dev/SKILL.md.tpl CHANGED
@@ -28,7 +28,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
28
28
 
29
29
  确定工作分支后先 `run.mjs show`;恢复时核对 context、代码与证据,不能把“继续”当作交付选择。
30
30
  非快速通道在 F4 / B4 首次落盘前 bind,再 `run.mjs start --kind feature|bug --size <规模> --input <checkpoint.json>`,补记真实完成的前置步骤。
31
- 每步完成、等待、阻塞和结束会话前 save;修复回 F5 / B4,交付进 F8 / B5。具体协议读 `<skills>/workflow/references/runs.md`。
31
+ 每步完成、等待、阻塞和结束会话前 save;修复回 F5 / B4,交付进 F8 / B5。具体协议读 `<skills>/workflow/references/runs.md` 与 [execution.md](../workflow/references/execution.md)。
32
32
  交付、自检、摘要与反馈处理后,末步标 completed,再 `run.mjs complete`,保存 completed(已完成)和 completed_at;已完成运行不覆盖。
33
33
 
34
34
  ## 功能开发流程
@@ -47,23 +47,23 @@ description: "Implement a feature or fix a bug in this project end to end: under
47
47
 
48
48
  ### F4 — 方案(落盘只看是否快速通道,写法按规模)
49
49
 
50
- 先读 [planning.md 的 F4](references/planning.md) 再选择快速通道;完整流程用 `requirement.mjs path plan` 写 `plan.md` 并 lint / sync,S / M 简版、L 完整版;M / L 确认后继续。
50
+ 先读 [planning.md 的 F4](references/planning.md) 再选择快速通道;完整流程用 `artifact.mjs finalize --kind plan` 将草稿收尾为 `plan.md`,S / M 简版、L 完整版;M / L 确认后记录 approval,再进入实现。
51
51
 
52
52
  ### F5 — 实现
53
53
 
54
- 读 [implementation.md 的 F5](references/implementation.md);小步修改、小步运行 `profile.build`,公共签名先看影响面;改动、配置清单与 SQL 脚本进入交付依据。
54
+ 读 [implementation.md 的 F5](references/implementation.md);完整流程先通过方案版本门禁,再小步修改、运行 `profile.build`,公共签名先看影响面;改动、配置清单与 SQL 脚本进入交付依据。
55
55
 
56
56
  ### F6 — 验证
57
57
 
58
- 读 [implementation.md 的 F6](references/implementation.md);执行相关测试、`profile.test` 与已配置的 lint;记录“验收项 → 测试或操作 → 结果”,已有失败与未验证项如实保留。
58
+ 读 [implementation.md 的 F6](references/implementation.md);完整流程执行前用 `run.mjs snapshot --id <id>` 取快照、执行后 save validation;两种通道都执行相关测试、`profile.test` 与 lint,记录“验收项 → 测试或操作 → 结果”,已有失败与未验证项如实保留。
59
59
 
60
60
  ### F7 — 审查、报告与用户选择
61
61
 
62
- 先读 [delivery.md 的 F7](references/delivery.md),完整流程按 project-review 第 1~7 步审查;优先独立子 agent,无则当前会话并如实署名。完整流程落报告、交用户、等修复或交付选择;内部审查不另起运行、不单独沉淀或记反馈。快速通道只在当前会话审查。
62
+ 先读 [delivery.md 的 F7](references/delivery.md),完整流程用 `review-handoff.mjs --id <id>` 生成交接材料,按 project-review 第 1~7 步审查;优先独立子 agent,无则当前会话并如实署名。子 agent 返回草稿与结构化结果,主 agent 用 `artifact.mjs finalize --kind review` 收尾,交用户、等修复或交付选择;内部审查不另起运行、不单独沉淀或记反馈。快速通道只在当前会话审查。
63
63
 
64
64
  ### F8 — 交付
65
65
 
66
- 读 [delivery.md 的 F8](references/delivery.md);完整流程取得交付选择后用 `requirement.mjs path delivery` 写 `delivery.md`、自检并汇总,快速通道仅对话交付。反馈用 `feedback.mjs add`;沉淀分类用 `resolve.mjs category dev`,详细授权、元信息与后续操作按该文执行。
66
+ 读 [delivery.md 的 F8](references/delivery.md);完整流程记录绑定本轮代码和报告的交付选择后,用 `artifact.mjs finalize --kind delivery` 收尾 `delivery.md` 并汇总,快速通道仅对话交付。反馈用 `feedback.mjs add`;沉淀分类用 `resolve.mjs category dev`,详细授权、元信息与后续操作按该文执行。
67
67
 
68
68
  ## 缺陷修复流程(`--bug`)
69
69
 
@@ -81,7 +81,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
81
81
 
82
82
  ### B4 — 修复与验证
83
83
 
84
- 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程通过 `requirement.mjs path plan` 归档旧版后,在原 `plan.md` 追加修复方案并更新文档头,不另建方案;M / L 确认后修复,复现测试由红变绿。
84
+ 先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4;完整流程在原方案草稿追加修复方案、更新文档头,用 `artifact.mjs finalize --kind plan` 收尾;M / L 确认后记录 approval、implement 再修复,复现测试由红变绿。
85
85
 
86
86
  ### B5 — 审查与交付
87
87
 
@@ -89,7 +89,7 @@ description: "Implement a feature or fix a bug in this project end to end: under
89
89
 
90
90
  ## Artifact Location
91
91
 
92
- 正式产物按 `<skills>/workflow/references/requirements.md` 归入 `workflow-run/docs/requirements/<需求>/<项目>/`,首次落盘前 bind;写入与归档细则见 [delivery.md 的 Artifact Location](references/delivery.md)。写完 sync,用输出的 cite 引用,lint 错误先修正。
92
+ 正式产物按 `<skills>/workflow/references/requirements.md` 归入 `workflow-run/docs/requirements/<需求>/<项目>/`,首次落盘前 bind;写入与归档细则见 [delivery.md 的 Artifact Location](references/delivery.md) 与 execution.md。正式产物统一 finalize,用输出的 cite 引用;中断先 resume。
93
93
  普通聊天的辅助文件默认放 `workflow-run/other/`,不绑定需求、不登记运行;源码、已有文件和用户指定路径沿用原规则。
94
94
 
95
95
  ## Rules
@@ -21,10 +21,12 @@
21
21
  ### B4 — 修复与验证
22
22
 
23
23
  - 修复前按 F4 的标准判定规模并告知用户(规模不询问确认);S 规模符合快速通道条件时照 F4 问用户是否走快速通道,问完等本轮答复再改代码:明确同意才走快速通道(不落盘),拒绝或未明确同意按完整流程。
24
- - **完整流程先把修复方案追加进 `plan.md`**:按 Artifact Location 运行 `requirement.mjs bind`(未绑定时),再用 `requirement.mjs path plan` 拿路径(已有 `plan.md` 时脚本会先把上一版归档到 `workflow-run/tmp/old-artifacts/`),把根因结论与修复方式写成 `plan.md` 的「修复方案」一节**追加**在原文之后(前面留一个空行与上一节隔开,避免标题被上一行吞掉)——保留已有方案正文、不另建文件;同时将文档头的分支更新为当前修复分支、日期更新为本次日期,不能只在追加的章节里写新分支,否则产物索引仍会归到旧分支。没有 `plan.md` 时按模板建一份,只填适用的节。写完 `requirement.mjs sync <方案路径>` 更新 `meta.json`,运行 `node <skills>/workflow/scripts/lint-doc.mjs <方案路径> --skill dev` 自检,再运行 `artifacts.mjs --branch <当前修复分支>` 确认 `latest.plan` 指向这份方案;M / L 等用户确认修复方式后再改代码,S 可以在同一轮确认并开始。修复中规模变化时说明变化依据,按新规模继续。
24
+ - **完整流程先把修复方案追加进 `plan.md`**:按 Artifact Location 绑定需求并创建 bug 运行;已有方案先复制到 tmp 草稿,保留正文,在末尾留空行后追加「修复方案」节(根因结论与修复方式),更新文档头为当前修复分支和本次日期。没有方案则按模板创建草稿,只填适用节。用 `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`。规模变化时说明依据、按新规模继续。
25
25
  - 做能消除根因的**最小改动**;B2 的测试由红变绿,相关已有测试保持通过(运行方式同 F6)。
26
26
  - 如果历史脏数据需要修正,写成 SQL 脚本交给用户,不直接执行。
27
27
 
28
28
  ### B5 — 审查与交付
29
29
 
30
30
  同 F7、F8:优先由独立子 agent 审查(没有子 agent 时在当前会话自查)并落盘 `review.md`,交报告后等待用户选择修复或交付;修复后验证、复审,再等选择,完整流程仅在用户选择交付后生成 `delivery.md`(「类型」写缺陷修复)。快速通道同样适用于缺陷修复:S 规模、用户在 B4 已同意走快速通道,不涉及配置 / SQL / 对外接口 / 表结构 / 权限 / 资金,且同类风险排查没有发现其他调用方受影响时,不绑定需求、不落任何产物文件,审查在当前会话做,交付在对话里一次完成并注明「DocNexus:未询问(快速通道不问沉淀)」;根因(证据链、修复方式)必须在对话里写清楚。完整交付时,交付说明的「根因」节必须写:证据链、修复方式、为什么这样修、同类风险排查结果;DocNexus 沉淀时根因是首要候选。
31
+
32
+ B4 的方案、实现进入与验证证据分开登记:方案 finalize 后,M / L 记录 approval,再 save implement: true;验证用执行前 snapshot 与实际 checks,B4 最后才标 completed。B5 按 execution.md 的交接、报告收尾、交付选择和交付收尾执行,报告完成不代表 B5 已完成。
@@ -5,7 +5,7 @@
5
5
  > 参考产物:{{最新审查报告路径(独立子 agent 或当前会话自查);方案路径(非快速通道都有)}}
6
6
  > DocNexus:{{尚未发起询问写「未询问」;沉淀后写 workflow-run/docnexus/library/<path>;没有值得沉淀的内容写「无需沉淀」,已询问但未成功入库(含用户拒绝)写「未沉淀」}}
7
7
 
8
- <!-- F7 审查报告交给用户且用户明确选择交付后,F8 / B5 才按此落盘到 requirement.mjs path delivery 给出的路径(workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md)。小改动每节写一两行即可,不适用的节写「无」;验证结果必须如实 -->
8
+ <!-- F7 审查报告交给用户且用户明确选择交付后,F8 / B5 才用 artifact.mjs finalize --kind delivery 将草稿收尾到 workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md。小改动每节写一两行即可,不适用的节写「无」;验证结果必须如实 -->
9
9
 
10
10
  ## 结果 *
11
11
 
@@ -7,12 +7,12 @@
7
7
  **S 快速通道不走本节**:在当前会话按 project-review 的标准清单自查,不写方案、不落 `review.md`、不绑定需求、不交报告等选择;审查结论写进 F8 的对话交付。碰到快速通道的退出条件时,再按下面的完整流程走。
8
8
 
9
9
  - 按 `project-review` skill 审本次改动,用户未指定深度时按 project-review 的「标准」审查。范围用 `node <skills>/workflow/scripts/review-scope.mjs --base <main_branch>`:分支已有的提交、未提交的改动和未跟踪的新文件一起列出。Step 0 确认不属于本需求的文件用 `--exclude <文件,文件>` 排除,它们不计入本次结论(见 Step 0「工作区状态与工作分支」);之后 project-review 的 `rules`、`locate.mjs` 都带同样的参数。
10
- - **优先由独立子 agent 审查**:派一个未参与本轮实现的子 agent,执行 project-review 的第 1~7 步(含复核和落盘报告)。只交接项目根、skills 路径、分支 / 基线、排除范围、审查深度(默认标准)、需求与验收标准、已确认决定、方案路径、验证命令与结果、上次报告路径;不要传实现者的自审结论或预设问题,让它自己读当前代码判断。审查期间主 agent 不再修改被审代码。子 agent 只审查、写审查产物,不修代码、不生成交付说明、不提交。
10
+ - **优先由独立子 agent 审查**:派一个未参与本轮实现的子 agent,执行 project-review 的第 1~7 步(含复核、报告草稿和结构化结果)。交接材料用 `review-handoff.mjs --id <id>` 自动生成,参数与结果结构见 `<skills>/workflow/references/execution.md`「自动审查交接」;不要传实现者的自审结论或预设问题,让它自己读当前代码判断。审查期间主 agent 不再修改被审代码。子 agent 只审查、写 tmp 草稿和结果 JSON,主 agent 负责 finalize、更新同一运行;不修代码、不生成交付说明、不提交。
11
11
  - **没有子 agent 时在当前会话审查**:按 project-review 第 1~7 步自己走完并落盘 `review.md`,报告的「审查者」写当前 agent(未派子 agent);问题表、复核、报告、等用户选择都不省。不要写成独立审查,也不要跳过审查直接进 F8。
12
- - **每轮必须落盘 `review.md`**:按 Artifact Location 先绑定需求,再按 project-review 第 7 步生成报告、运行 lint 和 sync。问题表、影响面、未覆盖项都要保留;没有发现也生成报告。只跳过 project-review 第 8 步沉淀与第 9 步反馈,沉淀和反馈留给 dev F8 统一处理;报告的元信息固定写「未询问(由 dev 交付统一处理)」。F8 只更新交付说明的沉淀状态,不将内部审查报告同步为交付的沉淀结果,避免把一次询问或沉淀重复计数。本轮尚无交付说明,不能把缺少 `delivery.md` 当成漏项;旧交付说明只能作为历史参考,当前需求与验证以本次交接为准。
12
+ - **每轮必须落盘 `review.md`**:按 Artifact Location 先绑定需求,再按 project-review 第 7 步生成草稿与结构化结果,由主 agent 用 `artifact.mjs finalize --kind review` 统一自检、落盘和登记证据。问题表、影响面、未覆盖项都要保留;没有发现也生成报告。只跳过 project-review 第 8 步沉淀与第 9 步反馈,沉淀和反馈留给 dev F8 统一处理;报告的元信息固定写「未询问(由 dev 交付统一处理)」。F8 只更新交付说明的沉淀状态,不将内部审查报告同步为交付的沉淀结果,避免把一次询问或沉淀重复计数。本轮尚无交付说明,不能把缺少 `delivery.md` 当成漏项;旧交付说明只能作为历史参考,当前需求与验证以本次交接为准。
13
13
  - **先交报告,再等选择**:主 agent 读取报告,将报告内容与路径交给用户,明确询问「修复报告中的问题,还是按当前结果交付?」并等待本轮明确答复。没有发现时也要等用户选择交付;答复含糊或未答复时留在 F7。此时**不创建、不覆盖 `delivery.md`,不提前进入提交、PR 或沉淀环节**。
14
14
  - **修复问题**:按用户选定的问题回到 F5 修复、F6 验证,再由未参与修复的子 agent(没有子 agent 时在当前会话)重新走 F7;复审更新 `review.md`,旧版按产物规则归档,逐条核对「已修复 / 仍存在 / 不再适用」。再次交报告、等待选择,不因已修复就自动交付。用户自己修复后也走 F6 → F7,不能只凭口头说已修复关闭问题。
15
- - **交付**:确认报告对应当前代码;审查后代码有变动就先回 F6 → F7。仍有已复核的 CRITICAL / HIGH 时,明确建议先修复,说明具体风险并让用户确认是否仍按当前结果交付;不能将一般的「交付」视为接受未说明的严重风险。用户明确接受遗留风险后才进 F8,如实记录遗留问题与未验证项,不得把带问题交付写成「审查通过」或「建议合并」。MEDIUM / LOW 的处理结果也写进交付说明(快速通道写在对话里)。
15
+ - **交付**:按 execution.md 保存 decision,绑定报告版本与代码摘要;确认报告对应当前代码;审查后代码有变动就先回 F6 → F7。仍有已复核的 CRITICAL / HIGH 时,明确建议先修复,说明具体风险并让用户确认是否仍按当前结果交付;不能将一般的「交付」视为接受未说明的严重风险。用户明确接受遗留风险后才进 F8,如实记录遗留问题与未验证项,不得把带问题交付写成「审查通过」或「建议合并」。MEDIUM / LOW 的处理结果也写进交付说明(快速通道写在对话里)。
16
16
 
17
17
  ### F8 — 交付
18
18
 
@@ -24,10 +24,12 @@
24
24
 
25
25
  完整流程:
26
26
 
27
- 1. **落盘交付说明**:模板路径用 `node <skills>/workflow/scripts/resolve.mjs template dev delivery-template.md` 取,写到 `requirement.mjs path delivery` 给出的路径(见 Artifact Location)。元信息行的「对比分支」写当前分支和 `profile.main_branch`,`artifacts.mjs`、project-review、上线方案靠它找到这份交付;「参考产物」写最新审查报告,有方案(`plan.md`)时也写方案路径。「审查」节记录报告结论、修复与复审结果、用户选择交付及接受的遗留风险。尚未发起沉淀询问时,元信息先写「未询问」,再按第 5 步更新。小改动每节一两行即可,不适用的节写「无」,但验证结果必须如实。
28
- 2. **自检**:运行 `node <skills>/workflow/scripts/lint-doc.mjs <交付路径> --skill dev --template delivery-template.md`,有「错误」先修正。
27
+ 1. **落盘交付说明**:模板路径用 `node <skills>/workflow/scripts/resolve.mjs template dev delivery-template.md` 取,先写到 tmp 草稿,按 execution.md 用 `artifact.mjs finalize --kind delivery` 发布(见 Artifact Location)。元信息行的「对比分支」写当前分支和 `profile.main_branch`,`artifacts.mjs`、project-review、上线方案靠它找到这份交付;「参考产物」写最新审查报告,有方案(`plan.md`)时也写方案路径。「审查」节记录报告结论、修复与复审结果、用户选择交付及接受的遗留风险。尚未发起沉淀询问时,元信息先写「未询问」,再按第 5 步更新。小改动每节一两行即可,不适用的节写「无」,但验证结果必须如实。
28
+ 2. **自检与收尾**:finalize 内部使用知识库交付模板检查草稿,有错误先修正;成功输出正式路径、cite 和版本。不要直接覆盖正式文件后用 sync 代替。
29
29
  3. **对话里给摘要**:结果、验证(含未验证项)、最新审查报告路径与结论、遗留问题和用户接受的风险、配置 / SQL 有无、交付文件路径;不必把全文贴进对话。
30
30
  4. **记录运行反馈**(不问用户):按 `<skills>/workflow/references/feedback.md` 运行 `node <skills>/workflow/scripts/feedback.mjs add --skill dev --model <模型名> --mode <feature|bug> --size <S|M|L> --fast <yes|no> --rounds <提问轮数> --corrections <用户纠正理解的次数> --acceptance <已验证>/<总数> --baseline-failures <n>`,有跳过的步骤、不清楚或做不到的规则、用户的抱怨时再加 `--skipped` / `--unclear` / `--feedback`。只写过程,不写代码和业务名词;报错就提一句,不影响交付。
31
+ 完成上述交付摘要与反馈后,按运行状态协议将 F8(bug 为 B5)标 completed 并 complete。下面的可选后续动作在完成标记后处理。
32
+
31
33
  5. **询问下一步**,不要自行执行:
32
34
  - 提交:给出建议的 commit message 和要 add 的文件(只含本需求的改动,Step 0 确认无关的不 add;建议把方案、审查报告和交付说明一起提交,随分支保留),用户同意后再 `git commit`;**不 push**,除非用户明确要求。
33
35
  - PR / MR:用户要提 PR / MR 时,运行 `node <skills>/workflow/scripts/pr-desc.mjs`(缺省当前分支、基线 `profile.main_branch`),它把本分支的交付说明、审查报告、技术方案、上线方案汇总成描述(没有交付说明时退回用提交记录和改动文件),把输出给用户;用 `gh pr create` / `glab mr create` 创建要用户明确同意。
@@ -44,5 +46,5 @@
44
46
  产物按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`,规则见 `<skills>/workflow/references/requirements.md`:
45
47
 
46
48
  - **需求名**:Step 0 已运行 `requirement.mjs which` 并问定名字。第一次落盘前运行 `requirement.mjs bind --name "<需求名>"`(用户明确同意按分支名生成时不带 `--name`);S 快速通道不 bind、不落盘。缺陷修复同样处理(可以选择挂到原需求下)。
47
- - **路径**:交付说明用 `requirement.mjs path delivery`,方案(非快速通道一律落,S / M 写简版)用 `requirement.mjs path plan`,写到输出的 `path`;文件名固定,已有旧版时直接写新版,上一版由脚本归档(输出的 `previous`)。缺陷修复在 B4 把根因与修复方式**追加**到同一个 `plan.md`(不另建文件)。
48
- - 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`;输出里 `archived` 非空(上一版已归档到 `workflow-run/tmp/old-artifacts/`)时告诉用户归档了哪些文件,请用户确认不再需要后自己删除;输出里 `commit` 非空(独立文档仓库模式)时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物(「参考产物」等)写 `requirement.mjs path` 输出的 `cite`。
49
+ - **正式写入**:按 `<skills>/workflow/references/execution.md`,方案、审查、交付都先写 tmp 草稿,再用 `artifact.mjs finalize --kind plan|review|delivery` 完成自检、旧版归档、索引与运行证据登记。缺陷修复在 B4 的方案草稿中保留原文并追加修复方案,不另建正式文件。
50
+ - 使用输出的 path / cite 引用;previous 非空时告知上一版归档位置,不能替用户删除。中断先 `artifact.mjs resume --id <id>`,不能继续 sync / save 覆盖待办。独立文档仓库在交付完成后运行 pending,按 requirements.md 提示提交。已完成交付的 wiki/DocNexus 元信息更新仍显式 sync。
@@ -4,6 +4,8 @@
4
4
 
5
5
  ### F5 — 实现
6
6
 
7
+ 完整流程先按 `<skills>/workflow/references/execution.md`「方案与实现门禁」进入 F5(bug 在 B4 记录 implement);M / L 的 approval 必须对应当前已收尾方案。
8
+
7
9
  - **小步推进**:按逻辑分步实现,一步改完(或改了公共签名、跨了模块)运行 `profile.build`(没有则用对应构建工具的编译命令)确认通过,再进入下一步。不必每改一个文件就编译,代码没变时不重复跑。
8
10
  - **改动前看影响面**:要改公共方法、接口签名、DTO 字段时,先 `node <skills>/code-graph/scripts/cg.mjs entry <Class.method>`(按本轮 CodeGraph 通道),把会被波及的入口和调用方纳入本次改动或写进交付说明。
9
11
  - **贴合现有代码**:沿用参照实现的写法;不顺手重构、不改无关代码、不升级依赖。看到范围外的问题记进交付说明,不在本次修。
@@ -13,6 +15,8 @@
13
15
 
14
16
  ### F6 — 验证
15
17
 
18
+ 完整流程按 `<skills>/workflow/references/execution.md`「验证证据」,在执行前 snapshot,执行后 save validation;只有代码快照仍一致,结果才能登记。feature 完成 F6 后进入 F7,bug 完成 B4 后进入 B5。快速通道不调用运行命令,下面的构建、测试与验收验证仍执行。
19
+
16
20
  - 按验收标准补充或更新单元测试 / 集成测试,测试放在项目既有测试目录、沿用既有测试框架。
17
21
  - **验收项对应到证据**:F1 / F3 的每条验收标准写明靠哪个测试或手动操作验证、结果如何;没有测试也没法操作的标「未验证」并写原因。交付说明「验证」节的表格按这个填,快速通道在对话里列同样的对应。
18
22
  - 先跑相关测试(`profile.test_single`,或代码图谱的 `impact` 选出的测试),修到通过;最后跑一次 `profile.test` 全量(之后又改了代码就再跑)。有 `profile.lint` 时一并运行。全量里出现、基线没跑到的失败,先看失败的测试是否碰到本次改动的代码,确认无关的按已有失败记录并写明依据。按本轮 CodeGraph 通道分析相关测试;script 模式取自 `node <skills>/code-graph/scripts/cg.mjs impact --base <main_branch>` 输出的 `tests`;`impact` 的 `entry_points`、`sql`、`config_keys` 写进交付说明(受影响的接口 / 消费者 / 定时任务、表、配置)。改动碰到 SQL、实体或 DDL 时运行 `node <skills>/workflow/scripts/tables.mjs --base <main_branch>`,对其中的表再核对一次实际表结构(见 `<skills>/workflow/references/tables.md`),结果写进交付说明的 SQL 节。
@@ -4,7 +4,7 @@
4
4
  > 需求来源:{{对话 / PRD 链接}} | 参考记忆:{{workflow-run/docnexus/library/... 或「无」}}
5
5
 
6
6
  <!-- 非快速通道一律落盘:S / M 只需要第 1、3、4、6 节,每节几行即可;L 写完整。走 S 快速通道时不写本文件。
7
- 缺陷修复在 B4 追加一节「## 修复方案(根因 + 修复方式)」,前面留一个空行与上一节隔开,保留原方案正文;文档头的分支与日期更新为当前修复分支和本次日期,上一版由 path plan 归档。
7
+ 缺陷修复在 B4 的草稿中追加一节「## 修复方案(根因 + 修复方式)」,前面留一个空行与上一节隔开,保留原方案正文;文档头更新为当前修复分支和本次日期,上一版由 artifact.mjs finalize --kind plan 归档。
8
8
  标题里的「方案」同时覆盖功能开发与缺陷修复两种用法。 -->
9
9
 
10
10
  ## 1. 需求要点与验收标准
@@ -40,6 +40,6 @@
40
40
 
41
41
  **落盘前绑定需求名**:Step 0 已经问定需求名;确定不走快速通道、第一次要落盘时,按 Artifact Location 运行 `requirement.mjs bind`(已绑定则跳过),之后的方案、审查、交付、技术方案、上线方案都归到这个需求下。S 快速通道不绑定。
42
42
 
43
- **S 规模快速通道(问用户)**:判定为 S 规模,且改动**不涉及**配置项、SQL / DDL、对外接口(HTTP 接口签名、MQ 消息体、对外 DTO)、表结构、权限、资金,也没有 F3 中确认过的业务决定时,**明确询问用户是否走快速通道**:说明走快速通道时 F5~F6 照常(编译、测试都不省),审查按 F7 的快速通道说明在当前会话做,但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写(运行反馈仍照常记一行),F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续:明确同意才走快速通道;拒绝或答复没有明确同意,就按完整流程落盘交付(F4 方案 → F7 审查 → F8 交付)。** 实现中一旦碰到上面任何一项、改动超过 3 个文件,或用户要求落盘 → 退出快速通道:先停下后续实现,重新评估并说明规模,按 Artifact Location 绑定需求,回到 F4 补写 `plan.md` 并自检(缺陷修复按 B4 追加修复方案);M / L 等用户确认方案后再继续,S 按简版方案推进。之后回 F5 完成实现、F6 验证、F7 审查并生成 `review.md`,交报告后等待用户选择交付,不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问,不省审查。
43
+ **S 规模快速通道(问用户)**:判定为 S 规模,且改动**不涉及**配置项、SQL / DDL、对外接口(HTTP 接口签名、MQ 消息体、对外 DTO)、表结构、权限、资金,也没有 F3 中确认过的业务决定时,**明确询问用户是否走快速通道**:说明走快速通道时 F5~F6 照常(编译、测试都不省),审查按 F7 的快速通道说明在当前会话做,但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写(运行反馈仍照常记一行),F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续:明确同意才走快速通道;拒绝或答复没有明确同意,就按完整流程落盘交付(F4 方案 → F7 审查 → F8 交付)。** 实现中一旦碰到上面任何一项、改动超过 3 个文件,或用户要求落盘 → 退出快速通道:先停下后续实现,重新评估并说明规模,按 Artifact Location 绑定需求,回到 F4 补写方案草稿并 finalize 为 `plan.md`(缺陷修复按 B4 追加修复方案);M / L 等用户确认方案后再继续,S 按简版方案推进。之后回 F5 完成实现、F6 验证、F7 审查并生成 `review.md`,交报告后等待用户选择交付,不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问,不省审查。
44
44
 
45
- **方案一律落盘(走快速通道除外)**:S / M / L 都写方案文档,规模只决定详细程度和确认方式。方案模板:在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`,读输出的 `path`。方案落盘后运行 `node <skills>/workflow/scripts/lint-doc.mjs <方案路径> --skill dev` 自检;M / L 等用户确认后再写代码,S 可以在同一轮确认并开始(方案按简版写)。S 先按上面的快速通道问一次:同意则不写方案,不同意或未明确同意才落盘。
45
+ **方案一律落盘(走快速通道除外)**: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 先按上面的快速通道问一次:同意则不写方案,不同意或未明确同意才落盘。
@@ -1,10 +1,10 @@
1
1
  # 开工与运行状态
2
2
 
3
- 进入 Step 0 或恢复运行前读取;只读当前事项对应小节。完整状态协议复用 `<skills>/workflow/references/runs.md`。
3
+ 进入 Step 0 或恢复运行前读取;只读当前事项对应小节。完整状态协议复用 `<skills>/workflow/references/runs.md`;关键阶段进入方式与正式产物收尾按 `<skills>/workflow/references/execution.md`。
4
4
 
5
5
  ## 完整流程的运行状态
6
6
 
7
- 按 `<skills>/workflow/references/runs.md` 保存和恢复进度,状态统一在需求的 `meta.json`,不另建状态文件。确定工作分支后先 `run.mjs show`;用户要求继续时读取对应运行的 context、已完成步骤与等待事项,核对代码和证据后从保存的阶段恢复,不重走有效的已完成步骤。不能把“继续”当成用户选择交付。
7
+ 按 `<skills>/workflow/references/runs.md` 保存和恢复进度,状态统一在需求的 `meta.json`,不另建状态文件。确定工作分支后先 `run.mjs show`;有 pending_finalization 先按 execution.md 恢复/取消收尾,用户要求继续时读取对应运行的 context、已完成步骤与等待事项,核对代码和证据后从保存的阶段恢复,不重走有效的已完成步骤。不能把“继续”当成用户选择交付。
8
8
 
9
9
  新任务确定不走快速通道后,先绑定需求,再 `run.mjs start --kind feature|bug --size <规模> --input <checkpoint.json>`,把前置步骤、验收标准、已确认决定、范围、基线与待办补入第一份 checkpoint。功能开发在 F4 创建(Step0、F1~F3 按真实进度补记),缺陷修复在 B4 创建(Step0、B1~B3 补记);快速通道不 start、不 save。
10
10
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rowansenne/workflow-run",
3
- "version": "0.27.0",
3
+ "version": "0.28.0",
4
4
  "description": "项目级 Agent Skills 一键初始化:workflow / dev / project-review / code-graph / database-query / md-to-wiki / 技术与上线方案生成",
5
5
  "keywords": [
6
6
  "agent-skills",
@@ -12,7 +12,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
12
12
  - 开工运行 `node <skills>/workflow/scripts/resolve.mjs status`,按 `<skills>/workflow/references/capabilities.md` 复用本轮能力快照;DocNexus 必装,不可用先修复。
13
13
  - 审查范围以 `review-scope.mjs` 输出为准;只报本次引入的问题,范围外发现单列,不把没覆盖写成没问题。
14
14
  - 每条结论引用真实代码与文件行号,行号由 `locate.mjs` 定位;CRITICAL / HIGH 必须复核,有条件时交独立 agent。
15
- - dev 完整流程调用:执行第 1~7 步,零发现也落盘;只返回报告与证据,不修代码、不生成 delivery.md、不提交、不另开 review 运行,跳过第 8~9 步。
15
+ - dev 完整流程调用:执行第 1~7 步,零发现也落盘;只返回报告草稿与结构化证据,由主 agent finalize,不修代码、不生成 delivery.md、不提交、不另开 review 运行,跳过第 8~9 步。
16
16
  - dev 内部报告写「未询问(由 dev 交付统一处理)」,缺本轮 delivery.md 是正常时序;主 agent 交报告后等用户选修复或交付。S 快速通道仅当前会话审查。
17
17
  - 深审大改动的分角度并行查找须用户同意;写入知识库与其他对外动作仍须授权。
18
18
 
@@ -38,7 +38,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
38
38
 
39
39
  6. **复核**:必须先读 [verification.md](references/verification.md)。运行 `locate.mjs workflow-run/tmp/review/findings.json`,带相同范围;验证触发条件、防护与引入时间,排除误报,保留成立或待确认的证据。
40
40
 
41
- 7. **输出报告**:先读 [reporting.md 的第 7 步与 Artifact Location](references/reporting.md)。用 `resolve.mjs template project-review report.md` 取模板;正式报告落 review.md,sync、lint 后完整交给用户,灵活模式在对话给 findings。
41
+ 7. **输出报告**:先读 [reporting.md 的第 7 步与 Artifact Location](references/reporting.md)。用 `resolve.mjs template project-review report.md` 取模板;正式报告按 execution.md 用 `artifact.mjs finalize --kind review` 收尾为 review.md 后完整交给用户,灵活模式在对话给 findings。
42
42
 
43
43
  8. **沉淀到 DocNexus**:独立审查交报告后读 [reporting.md 的第 8 步](references/reporting.md)。有值得记录的才询问授权,分类用 `resolve.mjs category project-review`;沉淀结果写报告元信息并 sync。dev 内部不执行。
44
44
 
@@ -62,7 +62,7 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
62
62
 
63
63
  ## Artifact Location
64
64
 
65
- 正式报告按 `<skills>/workflow/references/requirements.md`,用 `requirement.mjs path review [--branch <目标分支>]` 获取路径、归档旧版;写完 sync,并运行 `lint-doc.mjs <路径> --skill project-review --facts`,错误修正后交付。具体执行读 reporting.md。
65
+ 正式报告按 `<skills>/workflow/references/requirements.md`,在目标工作分支用 `review-handoff.mjs --id <id>` 生成交接材料,报告草稿与结构化结果交 `artifact.mjs finalize --kind review` 收尾;事实用 `lint-doc.mjs <草稿> --skill project-review --facts`,错误修正后交付。具体执行读 reporting.md。
66
66
  普通聊天的分析与草稿默认在 `workflow-run/other/`,不 bind、不建运行、不写需求 meta.json;用户明确路径优先。
67
67
 
68
68
  ## Verification
@@ -4,15 +4,15 @@
4
4
 
5
5
  ## 运行状态
6
6
 
7
- 独立运行且确定要落盘完整报告时,先确定目标分支与需求名、绑定需求,按 `<skills>/workflow/references/runs.md` 用 kind `review` 创建/恢复运行,R1~R7 对应 SKILL.md 第 1~7 步;每步完成、等待用户或受阻时保存。报告落盘、自检并交给用户后,将 R7 标 completed 并 complete,记录“已完成”和完成时间。可选沉淀、反馈与后续动作按原规则处理。灵活模式只在对话里审查时不创建运行;dev 内部调用也不另起运行,由 dev 主 agent 把报告结果记录到 F7/B5。
7
+ 独立运行且确定要落盘完整报告时,先确定目标分支与需求名、绑定需求,按 `<skills>/workflow/references/runs.md` 用 kind `review` 创建/恢复运行,R1~R7 对应 SKILL.md 第 1~7 步;每步完成、等待用户或受阻时保存。报告落盘、自检并交给用户后,将 R7 标 completed 并 complete,记录“已完成”和完成时间。可选沉淀、反馈与后续动作按原规则处理。灵活模式只在对话里审查时不创建运行;dev 内部调用也不另起运行,由 dev 主 agent 用 finalize 把报告和证据记录到 F7/B5。正式 review 的交接快照与收尾命令见 `<skills>/workflow/references/execution.md`。
8
8
 
9
9
  ## dev 内部调用
10
10
 
11
- 优先由未参与本轮实现的子 agent 执行第 1~7 步;没有子 agent 时由当前会话的 dev 执行同样的步骤,报告「审查者」写当前 agent,不写成独立审查。完整流程必须落盘报告(零发现也写),不使用下文「灵活模式」免落盘;S 快速通道不落盘,不适用本节。跳过第 8~9 步,沉淀与反馈由 dev 交付时统一处理。只审代码、写报告,不修改业务代码、不生成 `delivery.md`、不提交。元信息写「未询问(由 dev 交付统一处理)」,不将 F8 的交付沉淀结果复制到内部审查报告;缺少本轮交付说明是正常时序,需求、已确认决定和验证结果以 dev 交接为准,旧交付说明只作历史参考。报告完成后交回主 agent,由主 agent 询问用户修复或交付。
11
+ 优先由未参与本轮实现的子 agent 执行第 1~7 步;没有子 agent 时由当前会话的 dev 执行同样的步骤,报告「审查者」写当前 agent,不写成独立审查。完整流程必须落盘报告(零发现也写),不使用下文「灵活模式」免落盘;S 快速通道不落盘,不适用本节。跳过第 8~9 步,沉淀与反馈由 dev 交付时统一处理。只审代码、写 tmp 报告草稿和结构化结果,交回 dev 主 agent finalize;不修改业务代码、不生成 `delivery.md`、不提交。元信息写「未询问(由 dev 交付统一处理)」,不将 F8 的交付沉淀结果复制到内部审查报告;缺少本轮交付说明是正常时序,需求、已确认决定和验证结果以 dev 交接为准,旧交付说明只作历史参考。报告完成后交回主 agent,由主 agent 询问用户修复或交付。
12
12
 
13
13
  ## 第 7 步 — 输出报告(dev 完整流程的自审同样执行本步,只跳过第 8~9 步)
14
14
 
15
- 尚未发起沉淀询问时,报告元信息先写「未询问」。按报告模板输出(`node <skills>/workflow/scripts/resolve.mjs template project-review report.md` 取 `path`),落盘规则见 Artifact Location。
15
+ 尚未发起沉淀询问时,报告元信息先写「未询问」。按报告模板输出(`node <skills>/workflow/scripts/resolve.mjs template project-review report.md` 取 `path`),按 `<skills>/workflow/references/execution.md`「自动审查交接」生成交接 JSON,返回报告草稿与 packet.result_schema 对应的结果;范围逐文件登记。独立 review 用本运行 finalize;dev 内部由主 agent finalize,同样验证报告仍对应当前代码、方案和验收。落盘规则见 Artifact Location。
16
16
 
17
17
  ## 第 8 步 — 沉淀到 DocNexus(需用户授权)
18
18
 
@@ -37,11 +37,11 @@
37
37
 
38
38
  审查报告按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`,规则见 `<skills>/workflow/references/requirements.md`:
39
39
 
40
- - 路径用 `node <skills>/workflow/scripts/requirement.mjs path review`(分支对比按 dev 分支加 `--branch <dev分支>`),写到输出的 `path`(文件名固定为 `review.md`);已有报告时脚本先把它归档,输出的 `previous` 是上次报告,复审对照它。
41
- - 退出码 2(这个分支还没绑定需求):问用户这个需求叫什么,默认值用输出的 `suggested_name`,再 `requirement.mjs bind --name "<需求名>" [--branch <dev分支>]`;用户不给名字时 `bind` 按分支名生成。
42
- - 报告同时完整输出到对话;落盘文件与对话内容一致
43
- - 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`;输出里 `archived` 非空(上一版已归档到 `workflow-run/tmp/old-artifacts/`)时告诉用户归档了哪些文件,请用户确认不再需要后自己删除;输出里 `commit` 非空(独立文档仓库模式)时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物(「参考产物」等)写 `requirement.mjs path` 输出的 `cite`
44
- - 写完运行 `node <skills>/workflow/scripts/lint-doc.mjs <报告路径> --skill project-review --facts` 自检:「错误」(缺必填章节、缺元信息行、残留 `{{...}}`)先修正;「在 diff 和代码里都找不到」的名字逐个核实,写错了就改成真实的名字
40
+ - 正式审查在目标分支工作区进行,绑定并创建 review 运行后,用 `review-handoff.mjs --id <id>` 固定代码快照和范围;各步保存实际进度,需求/范围变化后重新审查。其他分支的只读灵活审查仍按 diff 命令执行,不创建运行。
41
+ - 报告先写 tmp 草稿,另写结构化结果(findings、coverage);按 execution.md 用 `artifact.mjs finalize --kind review --packet <交接JSON> --result <结果JSON>` 收尾,输出 path / cite / previous。dev 内部只交回草稿与结果,不由子 agent 更新 meta。
42
+ - 正式报告同时完整交给用户,内容与落盘文件一致;独立 review 将 R7 标 completed 后 complete,dev 内部由主 agent 保存 waiting_user 等选择。
43
+ - 事实核对仍用 `lint-doc.mjs <草稿> --skill project-review --facts`;错误先修正,无法核实的标待确认。finalize 另校验模板、分支、代码快照与覆盖登记。
44
+ - previous 非空时说明旧版已归档,不能替用户删除;独立文档仓库按 requirements.md 运行 pending 后提示提交,dev 内部延后到 F8。已完成报告的沉淀/wiki 元信息更新仍用 sync。
45
45
 
46
46
  ## 终端命令
47
47
 
@@ -69,6 +69,7 @@ dev(确定工作分支 → 定需求名 → 理解需求 → 方案 → 实现
69
69
  | `references/docnexus.md` | 写入 DocNexus 的分类(`resolve.mjs category`)、按分类参考知识库(`knowledge.mjs`) |
70
70
  | `references/capabilities.md` | 开工快照、必装组件门槛、可选增强通道与统一失败处理 |
71
71
  | `references/status.md` | `/workflow status` 的输出格式 |
72
+ | `references/execution.md` | 关键阶段门禁、执行前代码快照、自动审查交接、统一产物收尾与中断恢复 |
72
73
  | `references/runs.md` | 完整流程在 meta.json 中的运行状态、步骤完成标记、保存与恢复、运行完成时间 |
73
74
  | `references/requirements.md` | 产物按需求归档(`workflow-run/docs/requirements/<需求名>/<项目名>/`):什么时候问需求名、`requirement.mjs` 绑定分支与给出落盘路径、`meta.json` |
74
75
  | `references/tables.md` | 确定改动涉及哪些表(`tables.mjs`)、只读拉取实际表结构 / 索引 / 行数核对(`query.mjs --schema --indexes`),没有库连接时怎么退回 |
@@ -0,0 +1,144 @@
1
+ // 文件发布与 meta 更新之间用同一 meta.json 中的待办恢复;不声称多个文件可一次原子提交。
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { randomUUID } from 'node:crypto';
5
+ import { FILES, parseBranch } from './artifact-model.mjs';
6
+ import { hash, assertWorkingBranch } from './code-snapshot.mjs';
7
+ import { layout } from './project.mjs';
8
+ import { readRun, assertRunVersion, applyCheckpoint } from './runs.mjs';
9
+ import { isDev, applyDevEvidence, assertReview, assertDelivery, reviewEvidence } from './run-gates.mjs';
10
+ import { updateMeta } from './meta-store.mjs';
11
+ import { OLD_DIR, indexArtifacts } from './requirements.mjs';
12
+
13
+ export const ARTIFACT_TEMPLATES = {
14
+ plan: ['dev', 'plan-template.md'], review: ['project-review', 'report.md'], delivery: ['dev', 'delivery-template.md'],
15
+ tech: ['create-tech-md-doc', 'template.md'], release: ['create-release-md-doc', 'template.md'],
16
+ };
17
+ const allowed = { feature: ['plan', 'review', 'delivery'], bug: ['plan', 'review', 'delivery'], review: ['review'], tech: ['tech'], release: ['release'] };
18
+ const relative = (root, file) => path.relative(root, file).split(path.sep).join('/');
19
+ const fileHash = (file) => fs.existsSync(file) ? hash(fs.readFileSync(file)) : null;
20
+
21
+ export function resumeFinalization(root, { branch, id }) {
22
+ const { req } = readRun(root, branch, id);
23
+ let result;
24
+ updateMeta(path.join(req.abs, 'meta.json'), (meta) => {
25
+ const p = meta.pending_finalization;
26
+ if (!p || p.run_id !== id) throw new Error('没有该运行待恢复的产物收尾');
27
+ const run = meta.runs[id];
28
+ assertRunVersion(run, branch, p.revision);
29
+ if (isDev(run)) assertWorkingBranch(root, run);
30
+ const staged = path.resolve(root, p.staged);
31
+ if (fileHash(staged) !== p.hash) throw new Error('收尾草稿缺失或已变化,保留待办;请恢复原草稿后重试');
32
+ const file = path.join(req.abs, `${FILES[p.kind]}.md`);
33
+ const current = fileHash(file);
34
+ if (current !== p.before && current !== p.hash) throw new Error('正式产物在收尾中断后被其他操作修改,请先核对并恢复;不会覆盖');
35
+ // 中断期间代码/报告也可能变化:发布前重新检查本轮门禁。
36
+ applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, { [p.kind]: fs.readFileSync(staged, 'utf8') });
37
+ if (p.kind === 'review' || (isDev(p.run) && p.kind === 'delivery')) {
38
+ if (p.kind === 'review') assertReview(root, req, p.run, { review: fs.readFileSync(staged, 'utf8') });
39
+ else assertDelivery(root, req, p.run);
40
+ }
41
+ if (current !== p.hash) {
42
+ if (p.previous) {
43
+ const archive = path.resolve(root, p.previous);
44
+ fs.mkdirSync(path.dirname(archive), { recursive: true });
45
+ if (fs.existsSync(archive) && fileHash(archive) !== p.before) throw new Error('归档版本已存在且内容不同,停止以免覆盖历史');
46
+ fs.copyFileSync(file, archive);
47
+ }
48
+ const tmp = path.join(req.abs, `.${FILES[p.kind]}.${p.id}.tmp`);
49
+ fs.writeFileSync(tmp, fs.readFileSync(staged));
50
+ fs.renameSync(tmp, file);
51
+ }
52
+ const versions = { ...(meta.versions ?? {}), [p.kind]: p.version };
53
+ const artifacts = indexArtifacts(req.abs, versions);
54
+ const latest = Object.fromEntries(Object.keys(FILES).map((k) => [k, artifacts.filter((a) => a.kind === k).at(-1)?.file ?? null]));
55
+ const { pending_finalization, ...rest } = meta;
56
+ result = { ok: true, path: relative(root, file), cite: layout(root).ref(file), previous: p.previous, version: p.version, lint: p.run.artifacts[p.kind].lint, run: p.run };
57
+ return { ...rest, versions, artifacts, latest, runs: { ...meta.runs, [id]: p.run }, updated: p.run.updated_at };
58
+ }, { root, allowFinalization: true });
59
+ return result;
60
+ }
61
+
62
+ export function abortFinalization(root, { branch, id }) {
63
+ const { req } = readRun(root, branch, id);
64
+ updateMeta(path.join(req.abs, 'meta.json'), (meta) => {
65
+ const p = meta.pending_finalization;
66
+ if (!p || p.run_id !== id) throw new Error('没有该运行待取消的产物收尾');
67
+ assertRunVersion(meta.runs[id], branch, p.revision);
68
+ const file = path.join(req.abs, `${FILES[p.kind]}.md`);
69
+ const current = fileHash(file);
70
+ if (current !== p.before && current !== p.hash) throw new Error('正式文件已被其他操作修改,先人工核对,不会覆盖');
71
+ if (current === p.hash && p.before !== p.hash) {
72
+ if (p.before === null) fs.unlinkSync(file);
73
+ else {
74
+ const archive = path.resolve(root, p.previous);
75
+ if (fileHash(archive) !== p.before) throw new Error('原版本归档缺失,不能安全取消');
76
+ const tmp = path.join(req.abs, `.${FILES[p.kind]}.${p.id}.tmp`);
77
+ fs.copyFileSync(archive, tmp); fs.renameSync(tmp, file);
78
+ }
79
+ }
80
+ const { pending_finalization, ...rest } = meta;
81
+ return rest;
82
+ }, { root, allowFinalization: true });
83
+ return { ok: true, aborted: true, run_id: id };
84
+ }
85
+
86
+ export function finalizeArtifact(root, { branch, id, revision, kind, text, input = {}, packet = null, result = null }, check) {
87
+ if (!FILES[kind] || typeof text !== 'string') throw new Error('需要有效的产物 kind 和草稿正文');
88
+ const { req } = readRun(root, branch, id);
89
+ const file = path.join(req.abs, `${FILES[kind]}.md`);
90
+ const wikiRecord = (s) => /^<!-- md-to-wiki: [^\n]*-->/.exec(s)?.[0] ?? null;
91
+ const existingWiki = fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null;
92
+ const draftWiki = wikiRecord(text);
93
+ if (existingWiki && draftWiki && existingWiki !== draftWiki) throw new Error('新版必须保留原 wiki 页面记录;页面变更由 wiki 发布流程处理');
94
+ if (existingWiki && !draftWiki) text = `${existingWiki}\n${text}`;
95
+ const digest = hash(text);
96
+ const key = hash(JSON.stringify({ id, revision, kind, digest, input, packet, result }));
97
+ let repeated = null;
98
+ updateMeta(path.join(req.abs, 'meta.json'), (meta) => {
99
+ const current = meta.runs[id];
100
+ if (current.last_finalization === key && !meta.pending_finalization) {
101
+ if (fileHash(path.join(req.abs, `${FILES[kind]}.md`)) !== digest) throw new Error('已收尾产物后来被修改,请用当前 revision 发起新的收尾');
102
+ repeated = { ok: true, already_finalized: true, path: `${req.dir}/${FILES[kind]}.md`, run: current }; return meta;
103
+ }
104
+ if (meta.pending_finalization) {
105
+ if (meta.pending_finalization.key !== key) throw new Error(`已有待完成收尾,先运行 artifact.mjs resume --id ${meta.pending_finalization.run_id}`);
106
+ return meta;
107
+ }
108
+ assertRunVersion(current, branch, revision);
109
+ if (isDev(current)) assertWorkingBranch(root, current);
110
+ if (!allowed[current.kind]?.includes(kind)) throw new Error('该产物种类不属于当前运行');
111
+ if (parseBranch(text) !== branch) throw new Error('草稿元信息的分支必须与运行分支一致');
112
+ const lint = check(text);
113
+ if (!lint?.ok) throw new Error(`草稿自检失败:${lint?.errors?.join(';') || '模板不可用'}`);
114
+ const at = new Date().toISOString();
115
+ const run = structuredClone(current);
116
+ // 文档收尾只能登记当前步骤,不能在一次落盘中跳到下游或替用户作确认。
117
+ if (Object.keys(input).some((k) => !['steps', 'status', 'waiting_for', 'reason', 'context'].includes(k))) throw new Error('收尾 checkpoint 只接受 steps / status / waiting_for / reason / context;阶段和用户选择用 run.mjs save');
118
+ const expectedStep = isDev(run) ? (kind === 'plan' ? (run.kind === 'feature' ? 'F4' : 'B4') : kind === 'review' ? (run.kind === 'feature' ? 'F7' : 'B5') : (run.kind === 'feature' ? 'F8' : 'B5')) : ({ review: 'R7', tech: 'T4', release: 'L4' })[run.kind];
119
+ if (run.stage !== expectedStep || Object.keys(input.steps ?? {}).some((s) => s !== expectedStep)) throw new Error(`产物应在 ${expectedStep} 收尾,只能更新该步骤`);
120
+ if (isDev(run) && kind === 'delivery') assertDelivery(root, req, run);
121
+ if ((fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null) !== existingWiki) throw new Error('wiki 发布记录在收尾期间变化,请重新读取后重试');
122
+ const before = fileHash(file);
123
+ const oldVersion = meta.versions?.[kind] ?? 1;
124
+ const version = before === null ? 1 : oldVersion + (before === digest ? 0 : 1);
125
+ const previous = before !== null && before !== digest ? relative(root, path.join(root, OLD_DIR, path.relative(path.join(root, 'workflow-run/docs/requirements'), req.abs), `${FILES[kind]}_v${oldVersion}.md`)) : null;
126
+ run.artifacts = { ...(run.artifacts ?? {}), [kind]: { hash: digest, version, path: relative(root, file), previous, lint, at } };
127
+ if (kind === 'plan' && current.artifacts?.plan?.hash !== digest) { run.plan_approval = null; run.implementation = null; run.validation = null; run.review = null; run.decision = null; }
128
+ applyCheckpoint(run, input, at, false);
129
+ if (kind === 'review') {
130
+ run.review = reviewEvidence(root, req, run, packet, result, { review: text });
131
+ run.decision = null;
132
+ }
133
+ applyDevEvidence(root, req, run, input, at, { [kind]: text });
134
+ run.history.at(-1).artifact = { kind, hash: digest, version };
135
+ run.revision++; run.updated_at = at; run.last_finalization = key;
136
+ const op = randomUUID();
137
+ const staged = path.join(root, 'workflow-run/tmp/finalize', `${op}.md`);
138
+ fs.mkdirSync(path.dirname(staged), { recursive: true });
139
+ fs.writeFileSync(staged, text, { flag: 'wx' });
140
+ return { ...meta, pending_finalization: { id: op, key, run_id: id, revision, kind, before, hash: digest, version, previous, staged: relative(root, staged), run, packet, checkpoint: input } };
141
+ }, { root, allowFinalization: true });
142
+ if (repeated) return repeated;
143
+ return resumeFinalization(root, { branch, id });
144
+ }