@rowansenne/workflow-run 0.28.0 → 0.29.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.
Files changed (45) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +88 -26
  3. package/bin/lib/artifact-context.mjs +2 -0
  4. package/bin/lib/doctor.mjs +1 -1
  5. package/bin/lib/install.mjs +1 -1
  6. package/create-release-md-doc/SKILL.md.tpl +1 -0
  7. package/create-tech-md-doc/SKILL.md.tpl +1 -1
  8. package/dev/SKILL.md.tpl +15 -7
  9. package/dev/agents/openai.yaml +2 -0
  10. package/dev/references/bug.md +4 -3
  11. package/dev/references/clarify.md +1 -1
  12. package/dev/references/delivery-template.md +1 -1
  13. package/dev/references/delivery.md +4 -4
  14. package/dev/references/implementation.md +1 -1
  15. package/dev/references/plan-template.md +7 -11
  16. package/dev/references/planning.md +7 -3
  17. package/dev/references/preflight.md +1 -1
  18. package/dev/references/requirement-template.md +32 -0
  19. package/dev/skill.json +10 -2
  20. package/nacos-config/SKILL.md.tpl +42 -0
  21. package/nacos-config/package.json +7 -0
  22. package/nacos-config/references/connection.md +47 -0
  23. package/nacos-config/scripts/config.mjs +288 -0
  24. package/nacos-config/skill.json +9 -0
  25. package/package.json +6 -2
  26. package/project-review/SKILL.md.tpl +1 -0
  27. package/project-review/references/review-method.md +1 -1
  28. package/project-review/skill.json +2 -1
  29. package/workflow/SKILL.md.tpl +13 -9
  30. package/workflow/lib/artifact-finalize.mjs +26 -12
  31. package/workflow/lib/artifact-model.mjs +2 -2
  32. package/workflow/lib/code-snapshot.mjs +8 -2
  33. package/workflow/lib/run-gates.mjs +41 -24
  34. package/workflow/lib/runs.mjs +8 -7
  35. package/workflow/references/architecture.md +41 -3
  36. package/workflow/references/capabilities.md +3 -1
  37. package/workflow/references/execution.md +13 -3
  38. package/workflow/references/requirements.md +4 -1
  39. package/workflow/references/runs.md +11 -8
  40. package/workflow/references/templates.md +2 -2
  41. package/workflow/scripts/artifact.mjs +1 -1
  42. package/workflow/scripts/pr-desc.mjs +2 -2
  43. package/workflow/scripts/review-handoff.mjs +5 -4
  44. package/workflow/scripts/template.mjs +3 -2
  45. package/workflow/skill.json +2 -1
@@ -1,11 +1,13 @@
1
1
  ---
2
2
  name: workflow
3
- description: "Entry point for this project's dev workflow skills: routes a request to the right skill (dev, project-review, database-query, code-graph, create-tech-md-doc, create-release-md-doc, md-to-wiki, DocNexus), owns the shared project profile (workflow/profile.json) and the wiki / DocNexus / database capability check, and keeps per-requirement artifacts. Use when the user invokes /workflow, asks what the workflow can do, sets up the project profile, checks integrations, wants a PR / MR description from this branch's artifacts, a local report of how well the workflow works, a local page to browse docs per requirement, or to change a doc template, or hands over a multi-stage task. Triggers: 从需求到上线 / 这个需求从头到尾帮我搞定 / skills 配好了吗 / 项目画像 / workflow status / 写 PR 描述 / 提个 PR / 工作流效果怎么样 / workflow report / 看看项目文档 / workflow view / 改模板 / workflow template. When a request clearly belongs to one skill, use that skill directly."
3
+ description: "Entry point for project workflow commands: /workflow, project profile, integration status, PR/MR descriptions, local reports, requirement document views and templates. Routes to dev only when the user explicitly invokes /dev or $dev, requests the dev/full development workflow, or resumes an authorized dev run. Ordinary analysis, code edits, bug fixes, tests, commits and pushes do not start dev or the full workflow. Other independently requested skills (review, database, Nacos, code graph, docs, wiki) retain their own entry rules. Triggers: skills 配好了吗 / 项目画像 / workflow status / 写 PR 描述 / 工作流效果怎么样 / workflow report / 看看项目文档 / workflow view / 改模板 / workflow template."
4
4
  ---
5
5
 
6
6
  # Workflow
7
7
 
8
- **开工能力**:先运行 `node <skills>/workflow/scripts/resolve.mjs status`,按 `<skills>/workflow/references/capabilities.md` 选择本轮能力与模板;同一项目链路复用已有快照,失败统一按该规则处理。
8
+ **先判入口**:普通分析、代码修改、测试与 Git 操作不自动启动 dev,也不因本 skill 被加载而进行流程开工检查;直接处理用户当前任务。只有用户实际调用 dev、明确要求使用完整开发工作流,或要求恢复已授权的 dev 运行时,才路由到 dev。
9
+
10
+ **工作流开工能力**:进入本 skill 的状态 / 画像 / 文档等具体功能后,运行 `node <skills>/workflow/scripts/resolve.mjs status`,按 `<skills>/workflow/references/capabilities.md` 选择本轮能力与模板;同一项目链路复用已有快照,失败统一按该规则处理。
9
11
 
10
12
  本项目个人开发工作流的入口:决定由哪个 skill 处理请求,维护所有 skill 共用的**项目画像**,并统一**增强能力探测**。本 skill 自身不写业务代码。
11
13
 
@@ -18,17 +20,19 @@ description: "Entry point for this project's dev workflow skills: routes a reque
18
20
  /workflow profile # 填写或更新项目画像
19
21
  /workflow report # 本地效果报告(审查发现与修复率、需求澄清、沉淀与复用、各分支链路)
20
22
  /workflow view # 项目文档视图:按需求浏览方案、交付、审查、技术 / 上线方案(本地静态页面)
21
- /workflow template [<模板>] [怎么改] # 修改 / 创建文档模板:tech、release、plan、delivery、review、checklist
23
+ /workflow template [<模板>] [怎么改] # 修改 / 创建文档模板:requirement、tech、release、plan、delivery、review、checklist
22
24
  ```
23
25
 
24
26
  ## 能力地图(路由)
25
27
 
26
28
  | 用户意图 | 交给 | 备注 |
27
29
  |---|---|---|
28
- | 开发新功能、改逻辑、加接口 | `dev` | 默认功能开发模式 |
29
- | 修 bug、排查报错、线上问题 | `dev --bug` | 先复现再修 |
30
+ | `/dev` / `$dev`,或明确要求使用 dev / 完整开发流程 | `dev` | 用户选择功能开发流程 |
31
+ | `/dev --bug`,或明确要求使用 dev 缺陷修复流程 | `dev --bug` | 用户选择修复流程 |
32
+ | 普通分析、改代码、修 bug、重构、测试、提交 / 推送 | 当前会话直接处理 | 不自动进入 dev,不创建需求或运行 |
30
33
  | 审代码、审分支、合并前检查 | `project-review` | |
31
34
  | 查库、跑 SQL、核对数据 | `database-query` | 只读优先 |
35
+ | 读 Nacos 远程配置、查参数或开关 | `nacos-config` | 按需只读,先确定环境与 Data ID |
32
36
  | 影响面、谁调用了、从哪些入口进来、topic 谁发谁收、定时任务、表在哪些 SQL 里 | `code-graph` | 需 CodeGraph 索引;`mq` / `jobs` / `tables` 不需要 |
33
37
  | 根据分支 diff 出技术方案 | `create-tech-md-doc` | 可带 `--prd` |
34
38
  | 根据分支 diff 出上线方案 | `create-release-md-doc` | 可带 `--tech` 复用技术方案 |
@@ -40,12 +44,12 @@ description: "Entry point for this project's dev workflow skills: routes a reque
40
44
  | 改技术方案 / 上线方案 / 交付说明 / 审查报告的模板,按样例建模板 | `/workflow template` | 草稿 → 校验与影响 → 用户确认后写入 DocNexus(知识库是模板唯一来源) |
41
45
  | 记住 / 查找项目决策与约定 | DocNexus(入口 skill `docnexus`) | 需已接入;写入必须用户授权 |
42
46
 
43
- 意图明确时直接按对应 skill 执行,不必先输出这张表。目标 skill 没有安装(`resolve.mjs status` 输出的 `skills` 里没有它,安装时用了 `--skills` 子集)→ 告诉用户可以运行 `npx @rowansenne/workflow-run --skills <名称>` 补装,不要假装执行。意图横跨多个阶段时按下面的「完整链路」逐段推进,每段结束告诉用户下一段是什么,由用户决定是否继续。走到哪一步不靠记忆:运行 `node <skills>/workflow/scripts/artifacts.mjs [--branch <分支>]`,它扫描 `workflow-run/docs/requirements/` 下的产物,按元信息行里的分支归组,输出每类最新的一份、wiki 发布记录和 `next`(下一步建议)。
47
+ 先遵守显式触发边界,不能把「帮我实现」「修这个 bug」「代码提交」「从头到尾处理」推断为启动 dev。用户明确要求独立能力时按对应 skill 执行,不必先输出这张表;直接要求提交代码时执行所需 Git 检查与提交,不先生成 PR 描述或补工作流文档。目标 skill 没安装时给出 `npx @rowansenne/workflow-run --skills <名称>` 补装命令,不假装执行。只有明确要求完整开发工作流时才按下面的完整链路逐段推进;用户只给出普通多步任务时直接处理,不套入 dev。已进入工作流时可用 `node <skills>/workflow/scripts/artifacts.mjs [--branch <分支>]` 读取进度;旧运行、绑定和 next 建议都不构成启动或恢复授权。
44
48
 
45
49
  ### 完整链路(从需求到上线)
46
50
 
47
51
  ```
48
- dev(确定工作分支 → 定需求名 → 理解需求 → 方案 → 实现 → 测试 → 优先独立子 agent 审查并落盘报告,无则在当前会话自查 → 用户选择修复或交付)
52
+ dev(确定工作分支 → 定需求名 → 理解与澄清 → 需求文档 → 方案 → 实现 → 测试 → 优先独立子 agent 审查并落盘报告,无则在当前会话自查 → 用户选择修复或交付)
49
53
  ↳ 修复:实现 → 验证 → 复审(无子 agent 时当前会话)→ 再次选择;交付:完整流程生成 delivery.md,S 快速通道只在对话交付、不落盘
50
54
  → create-tech-md-doc(M / L 规模)
51
55
  → md-to-wiki(发布技术方案,可选)
@@ -54,7 +58,7 @@ dev(确定工作分支 → 定需求名 → 理解需求 → 方案 → 实现
54
58
  → DocNexus 沉淀(可选,需授权)
55
59
  ```
56
60
 
57
- 开始完整链路时,先进入 dev 的 Step 0 确定本次工作分支,再运行 `node <skills>/workflow/scripts/requirement.mjs which` 确认需求名(见 `references/requirements.md`)。入口只转交用户明确给出或确认的名字,不把切换前从旧分支自动读到的名字当成用户已确认的需求名。**这里只问、不 bind**,等第一次真的要落盘产物时再由对应 skill `bind`。这样从入口进来也可以走 S 快速通道,不会提前创建需求目录和 `meta.json`。
61
+ 用户明确要求开始完整链路后,才进入 dev 的 Step 0 确定本次工作分支,再运行 `node <skills>/workflow/scripts/requirement.mjs which` 确认需求名(见 `references/requirements.md`)。入口只转交用户明确给出或确认的名字,不把切换前从旧分支自动读到的名字当成用户已确认的需求名。**这里只问、不 bind**,等第一次真的要落盘产物时再由对应 skill `bind`。这样从入口进来也可以走 S 快速通道,不会提前创建需求目录和 `meta.json`。
58
62
 
59
63
  提交、推送、发布 wiki、写入 DocNexus 都是对外动作,每一步都要用户明确同意。
60
64
 
@@ -87,7 +91,7 @@ dev(确定工作分支 → 定需求名 → 理解需求 → 方案 → 实现
87
91
  - 本 skill 只路由和维护 `profile.json`,不写业务代码;具体工作交给对应 skill,并遵守该 skill 的规则。
88
92
  - `profile.json` 只记录项目事实(含 `toolchain` 开发环境配置:JDK / Maven / Node 的路径),**不写密码、token、内网凭据**;路径里的变量在 `env_vars` 里声明。
89
93
  - 写 `toolchain` 前先用 `resolve.mjs env --check` 核对路径在本机存在;本机对不上、又只是个人差异的,写进个人的 `profile.local.json`(覆盖 `profile.json`),不要改团队那份。
90
- - 用户的请求明显只属于某个 skill 时,直接进入对应 skill,并复用本轮开工能力快照。
94
+ - 独立 skill 按自身入口执行;dev 必须先有显式流程授权。普通任务不加载 dev 的开工、需求归档或运行命令,也不为提交代码重启或补齐流程。
91
95
 
92
96
  ## 终端命令
93
97
 
@@ -3,18 +3,19 @@ import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { randomUUID } from 'node:crypto';
5
5
  import { FILES, parseBranch } from './artifact-model.mjs';
6
- import { hash, assertWorkingBranch } from './code-snapshot.mjs';
6
+ import { hash, assertWorkingBranch, snapshotReader } from './code-snapshot.mjs';
7
7
  import { layout } from './project.mjs';
8
8
  import { readRun, assertRunVersion, applyCheckpoint } from './runs.mjs';
9
- import { isDev, applyDevEvidence, assertReview, assertDelivery, reviewEvidence } from './run-gates.mjs';
9
+ import { isDev, coreSteps, applyDevEvidence, assertRequirement, assertPlanBasis, assertReview, assertDelivery, reviewEvidence } from './run-gates.mjs';
10
10
  import { updateMeta } from './meta-store.mjs';
11
11
  import { OLD_DIR, indexArtifacts } from './requirements.mjs';
12
12
 
13
13
  export const ARTIFACT_TEMPLATES = {
14
+ requirement: ['dev', 'requirement-template.md'],
14
15
  plan: ['dev', 'plan-template.md'], review: ['project-review', 'report.md'], delivery: ['dev', 'delivery-template.md'],
15
16
  tech: ['create-tech-md-doc', 'template.md'], release: ['create-release-md-doc', 'template.md'],
16
17
  };
17
- const allowed = { feature: ['plan', 'review', 'delivery'], bug: ['plan', 'review', 'delivery'], review: ['review'], tech: ['tech'], release: ['release'] };
18
+ const allowed = { feature: ['requirement', 'plan', 'review', 'delivery'], bug: ['requirement', 'plan', 'review', 'delivery'], review: ['review'], tech: ['tech'], release: ['release'] };
18
19
  const relative = (root, file) => path.relative(root, file).split(path.sep).join('/');
19
20
  const fileHash = (file) => fs.existsSync(file) ? hash(fs.readFileSync(file)) : null;
20
21
 
@@ -33,10 +34,12 @@ export function resumeFinalization(root, { branch, id }) {
33
34
  const current = fileHash(file);
34
35
  if (current !== p.before && current !== p.hash) throw new Error('正式产物在收尾中断后被其他操作修改,请先核对并恢复;不会覆盖');
35
36
  // 中断期间代码/报告也可能变化:发布前重新检查本轮门禁。
36
- applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, { [p.kind]: fs.readFileSync(staged, 'utf8') });
37
+ const getSnapshot = snapshotReader(root, p.run);
38
+ applyDevEvidence(root, req, p.run, p.checkpoint, p.run.updated_at, { [p.kind]: fs.readFileSync(staged, 'utf8') }, getSnapshot);
39
+ if (p.kind === 'plan') assertPlanBasis(root, req, p.run, { plan: fs.readFileSync(staged, 'utf8') });
37
40
  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);
41
+ if (p.kind === 'review') assertReview(root, req, p.run, { review: fs.readFileSync(staged, 'utf8') }, getSnapshot);
42
+ else assertDelivery(root, req, p.run, undefined, getSnapshot);
40
43
  }
41
44
  if (current !== p.hash) {
42
45
  if (p.previous) {
@@ -113,24 +116,35 @@ export function finalizeArtifact(root, { branch, id, revision, kind, text, input
113
116
  if (!lint?.ok) throw new Error(`草稿自检失败:${lint?.errors?.join(';') || '模板不可用'}`);
114
117
  const at = new Date().toISOString();
115
118
  const run = structuredClone(current);
119
+ const getSnapshot = snapshotReader(root, run);
116
120
  // 文档收尾只能登记当前步骤,不能在一次落盘中跳到下游或替用户作确认。
117
121
  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];
122
+ const expectedStep = isDev(run) ? (kind === 'requirement' ? (run.kind === 'feature' ? 'F3' : 'B3') : 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
123
  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);
124
+ let requirement = null;
125
+ if (kind === 'plan') {
126
+ requirement = assertRequirement(root, req, run);
127
+ if (run.steps[run.kind === 'feature' ? 'F3' : 'B3'].status !== 'completed') throw new Error('需求文档尚未完成,不能收尾方案');
128
+ }
129
+ if (isDev(run) && kind === 'delivery') assertDelivery(root, req, run, undefined, getSnapshot);
121
130
  if ((fs.existsSync(file) ? wikiRecord(fs.readFileSync(file, 'utf8')) : null) !== existingWiki) throw new Error('wiki 发布记录在收尾期间变化,请重新读取后重试');
122
131
  const before = fileHash(file);
123
132
  const oldVersion = meta.versions?.[kind] ?? 1;
124
133
  const version = before === null ? 1 : oldVersion + (before === digest ? 0 : 1);
125
134
  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; }
135
+ run.artifacts = { ...(run.artifacts ?? {}), [kind]: { hash: digest, version, path: relative(root, file), previous, lint, at,
136
+ ...(requirement ? { requirement: { hash: requirement.hash, version: requirement.version } } : {}) } };
137
+ if ((kind === 'plan' && (current.artifacts?.plan?.hash !== digest || current.artifacts?.plan?.requirement?.hash !== requirement.hash))
138
+ || (kind === 'requirement' && current.artifacts?.requirement?.hash !== digest)) {
139
+ run.plan_approval = null; run.implementation = null; run.validation = null; run.review = null; run.decision = null;
140
+ if (kind === 'requirement') for (const step of coreSteps(run).slice(1)) run.steps[step] = { status: 'pending' };
141
+ }
128
142
  applyCheckpoint(run, input, at, false);
129
143
  if (kind === 'review') {
130
- run.review = reviewEvidence(root, req, run, packet, result, { review: text });
144
+ run.review = reviewEvidence(root, req, run, packet, result, { review: text }, getSnapshot);
131
145
  run.decision = null;
132
146
  }
133
- applyDevEvidence(root, req, run, input, at, { [kind]: text });
147
+ applyDevEvidence(root, req, run, input, at, { [kind]: text }, getSnapshot);
134
148
  run.history.at(-1).artifact = { kind, hash: digest, version };
135
149
  run.revision++; run.updated_at = at; run.last_finalization = key;
136
150
  const op = randomUUID();
@@ -1,8 +1,8 @@
1
1
  // 正式需求产物的统一纯模型;不扫描目录、不修改状态。
2
2
  import { sections, section, tableRows, listItems, meta, isEmpty } from './document-model.mjs';
3
3
 
4
- export const FILES = { plan: 'plan', delivery: 'delivery', review: 'review', tech: 'tech-doc', release: 'release-doc' };
5
- export const LABELS = { plan: '方案', delivery: '交付说明', review: '审查报告', tech: '技术方案', release: '上线方案' };
4
+ export const FILES = { requirement: 'requirement', plan: 'plan', delivery: 'delivery', review: 'review', tech: 'tech-doc', release: 'release-doc' };
5
+ export const LABELS = { requirement: '需求文档', plan: '方案', delivery: '交付说明', review: '审查报告', tech: '技术方案', release: '上线方案' };
6
6
  export const KINDS = Object.keys(FILES).map((kind) => ({ kind, label: LABELS[kind] }));
7
7
 
8
8
  // 文件名 → { kind, version };不是需求目录里的产物返回 null
@@ -48,8 +48,14 @@ export function codeSnapshot(root, run) {
48
48
  return { ...snapshot, digest: hash(JSON.stringify({ ...snapshot, entries })) };
49
49
  }
50
50
 
51
- export function assertSnapshot(root, run, snapshot) {
52
- const current = codeSnapshot(root, run);
51
+ // 只在同一轮同步校验内复用;新的操作和发布阶段各自创建 reader。
52
+ export function snapshotReader(root, run) {
53
+ let current;
54
+ return () => current ??= codeSnapshot(root, run);
55
+ }
56
+
57
+ export function assertSnapshot(root, run, snapshot, getSnapshot = snapshotReader(root, run)) {
58
+ const current = getSnapshot();
53
59
  if (!snapshot?.digest || snapshot.digest !== current.digest) throw new Error('代码或基线已变化,原验证/审查证据已失效;重新生成快照、验证并审查');
54
60
  return current;
55
61
  }
@@ -2,10 +2,10 @@
2
2
  import fs from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { FILES, parseBranch } from './artifact-model.mjs';
5
- import { hash, assertSnapshot, assertWorkingBranch } from './code-snapshot.mjs';
5
+ import { hash, assertSnapshot, assertWorkingBranch, snapshotReader } from './code-snapshot.mjs';
6
6
 
7
7
  export const isDev = (run) => ['feature', 'bug'].includes(run.kind);
8
- export const coreSteps = (run) => run.kind === 'feature' ? ['F4', 'F5', 'F6', 'F7', 'F8'] : ['B4', 'B5'];
8
+ export const coreSteps = (run) => run.kind === 'feature' ? ['F3', 'F4', 'F5', 'F6', 'F7', 'F8'] : ['B3', 'B4', 'B5'];
9
9
 
10
10
  export function receipt(root, req, run, kind, contents = {}) {
11
11
  const record = run.artifacts?.[kind];
@@ -15,32 +15,43 @@ export function receipt(root, req, run, kind, contents = {}) {
15
15
  return record;
16
16
  }
17
17
 
18
+ export function assertRequirement(root, req, run, contents) {
19
+ return receipt(root, req, run, 'requirement', contents);
20
+ }
21
+
22
+ export function assertPlanBasis(root, req, run, contents) {
23
+ const requirement = assertRequirement(root, req, run, contents);
24
+ const plan = receipt(root, req, run, 'plan', contents);
25
+ if (plan.requirement?.hash !== requirement.hash || plan.requirement.version !== requirement.version) throw new Error('方案依据的需求版本已变化,请根据当前 requirement.md 重新收尾方案');
26
+ return plan;
27
+ }
28
+
18
29
  export function assertPlan(root, req, run, contents) {
19
30
  assertWorkingBranch(root, run);
20
- const plan = receipt(root, req, run, 'plan', contents);
31
+ const plan = assertPlanBasis(root, req, run, contents);
21
32
  if (run.size !== 'S' && (run.plan_approval?.hash !== plan.hash || run.plan_approval.version !== plan.version)) throw new Error('M / L 方案尚未由用户确认,或确认后方案已变化;先记录 approval.confirmed');
22
33
  return plan;
23
34
  }
24
35
 
25
- export function assertValidation(root, req, run, contents) {
36
+ export function assertValidation(root, req, run, contents, getSnapshot = snapshotReader(root, run)) {
26
37
  const plan = assertPlan(root, req, run, contents);
27
38
  if (run.implementation?.plan !== plan.hash) throw new Error('尚未通过方案门禁进入实现,请先进入 F5;bug 保存 implement: true');
28
- assertSnapshot(root, run, run.validation?.snapshot);
39
+ assertSnapshot(root, run, run.validation?.snapshot, getSnapshot);
29
40
  return run.validation;
30
41
  }
31
42
 
32
- export function assertReview(root, req, run, contents) {
33
- const validation = isDev(run) ? assertValidation(root, req, run, contents) : null;
43
+ export function assertReview(root, req, run, contents, getSnapshot = snapshotReader(root, run)) {
44
+ const validation = isDev(run) ? assertValidation(root, req, run, contents, getSnapshot) : null;
34
45
  const report = receipt(root, req, run, 'review', contents);
35
46
  if (!run.review || run.review.report_hash !== report.hash || run.review.report_version !== report.version
36
47
  || run.review.inputs !== hash(JSON.stringify(reviewInputs(run)))
37
48
  || (validation && run.review.snapshot.digest !== validation.snapshot.digest)) throw new Error('缺少对应本轮验证和报告版本的审查证据,请重新审查');
38
- if (!validation) assertSnapshot(root, run, run.review.snapshot);
49
+ if (!validation) assertSnapshot(root, run, run.review.snapshot, getSnapshot);
39
50
  return run.review;
40
51
  }
41
52
 
42
- export function assertDelivery(root, req, run, contents) {
43
- const review = assertReview(root, req, run, contents);
53
+ export function assertDelivery(root, req, run, contents, getSnapshot = snapshotReader(root, run)) {
54
+ const review = assertReview(root, req, run, contents, getSnapshot);
44
55
  const decision = run.decision;
45
56
  if (decision?.action !== 'deliver' || decision.confirmed !== true || decision.report_hash !== review.report_hash
46
57
  || decision.report_version !== review.report_version || decision.code !== review.snapshot.digest) throw new Error('进入交付前必须由用户明确选择本轮报告的交付;旧交付选择不再有效');
@@ -48,12 +59,12 @@ export function assertDelivery(root, req, run, contents) {
48
59
  if (serious.some((f) => !decision.accepted_risks?.includes(f.id))) throw new Error('严重遗留风险必须逐项说明并取得用户明确接受,记录 accepted_risks 中的问题 id');
49
60
  }
50
61
 
51
- export function applyDevEvidence(root, req, run, patch, at, contents = {}) {
62
+ export function applyDevEvidence(root, req, run, patch, at, contents = {}, getSnapshot = snapshotReader(root, run)) {
52
63
  if (!isDev(run)) return;
53
64
  for (const step of coreSteps(run)) if (run.steps[step].status === 'skipped') throw new Error(`完整 dev 核心步骤不能跳过:${step}`);
54
65
  if (patch.approval !== undefined) {
55
66
  if (patch.approval?.confirmed !== true) throw new Error('approval 必须记录用户明确确认:confirmed: true');
56
- const plan = receipt(root, req, run, 'plan', contents);
67
+ const plan = assertPlanBasis(root, req, run, contents);
57
68
  run.plan_approval = { hash: plan.hash, version: plan.version, at };
58
69
  }
59
70
  const implementing = patch.implement === true || (run.kind === 'feature' && patch.stage === 'F5');
@@ -71,18 +82,24 @@ export function applyDevEvidence(root, req, run, patch, at, contents = {}) {
71
82
  const v = patch.validation;
72
83
  if (!Array.isArray(v?.checks) || !v.checks.length || v.checks.some((c) => !c.command?.trim()
73
84
  || !['passed', 'failed', 'unverified'].includes(c.result) || (c.result !== 'passed' && !c.reason?.trim()))) throw new Error('validation.checks 需要命令/操作、passed / failed / unverified;失败或未验证须写 reason');
74
- const snapshot = assertSnapshot(root, run, v.snapshot);
85
+ const snapshot = assertSnapshot(root, run, v.snapshot, getSnapshot);
75
86
  run.validation = { snapshot, checks: v.checks, at };
76
87
  run.review = null; run.decision = null;
77
88
  if (run.kind === 'feature') for (const step of ['F7', 'F8']) run.steps[step] = { status: 'pending' };
78
89
  }
79
90
  if (patch.decision?.action === 'deliver') {
80
91
  if (run.kind === 'feature' && run.steps.F7.status !== 'completed') throw new Error('审查步骤 F7 尚未完成,不能选择交付');
81
- const review = assertReview(root, req, run, contents);
92
+ const review = assertReview(root, req, run, contents, getSnapshot);
82
93
  run.decision = { ...run.decision, code: review.snapshot.digest, report_hash: review.report_hash, report_version: review.report_version };
83
- assertDelivery(root, req, run, contents);
94
+ assertDelivery(root, req, run, contents, getSnapshot);
84
95
  }
85
96
  const completed = (s) => patch.steps?.[s]?.status === 'completed';
97
+ const requirementStep = run.kind === 'feature' ? 'F3' : 'B3';
98
+ if (completed(requirementStep)) assertRequirement(root, req, run, contents);
99
+ if (patch.stage === (run.kind === 'feature' ? 'F4' : 'B4')) {
100
+ assertRequirement(root, req, run, contents);
101
+ if (run.steps[requirementStep].status !== 'completed') throw new Error('需求文档尚未完成,不能进入方案/修复阶段');
102
+ }
86
103
  if (run.kind === 'feature') {
87
104
  if (completed('F4')) receipt(root, req, run, 'plan', contents);
88
105
  if (patch.stage === 'F6' || completed('F5')) {
@@ -91,18 +108,18 @@ export function applyDevEvidence(root, req, run, patch, at, contents = {}) {
91
108
  }
92
109
  if (patch.stage === 'F7' || completed('F6')) {
93
110
  if (run.steps.F5.status !== 'completed') throw new Error('实现步骤 F5 尚未完成');
94
- assertValidation(root, req, run, contents);
111
+ assertValidation(root, req, run, contents, getSnapshot);
95
112
  if (patch.stage === 'F7' && run.steps.F6.status !== 'completed') throw new Error('验证步骤 F6 尚未完成');
96
113
  }
97
- if (completed('F7')) assertReview(root, req, run, contents);
98
- if (patch.stage === 'F8' || completed('F8')) assertDelivery(root, req, run, contents);
114
+ if (completed('F7')) assertReview(root, req, run, contents, getSnapshot);
115
+ if (patch.stage === 'F8' || completed('F8')) assertDelivery(root, req, run, contents, getSnapshot);
99
116
  if (completed('F8')) receipt(root, req, run, 'delivery', contents);
100
117
  } else {
101
118
  if (completed('B4') || patch.stage === 'B5') {
102
- assertValidation(root, req, run, contents);
119
+ assertValidation(root, req, run, contents, getSnapshot);
103
120
  if (patch.stage === 'B5' && run.steps.B4.status !== 'completed') throw new Error('修复与验证步骤 B4 尚未完成');
104
121
  }
105
- if (completed('B5')) { assertDelivery(root, req, run, contents); receipt(root, req, run, 'delivery', contents); }
122
+ if (completed('B5')) { assertDelivery(root, req, run, contents, getSnapshot); receipt(root, req, run, 'delivery', contents); }
106
123
  }
107
124
  const event = run.history.at(-1);
108
125
  if (patch.approval) event.approval = run.plan_approval;
@@ -112,13 +129,13 @@ export function applyDevEvidence(root, req, run, patch, at, contents = {}) {
112
129
 
113
130
  export function reviewInputs(run) {
114
131
  const facts = Object.fromEntries(['summary', 'acceptance', 'decisions', 'scope', 'baseline'].filter((k) => run.context[k] !== undefined).map((k) => [k, run.context[k]]));
115
- return { facts, scope: run.scope, plan: run.artifacts?.plan ?? null, validation: run.validation ?? null };
132
+ return { facts, requirement: run.artifacts?.requirement ?? null, scope: run.scope, plan: run.artifacts?.plan ?? null, validation: run.validation ?? null };
116
133
  }
117
134
 
118
- export function reviewEvidence(root, req, run, packet, result, contents) {
135
+ export function reviewEvidence(root, req, run, packet, result, contents, getSnapshot = snapshotReader(root, run)) {
119
136
  if (!packet || packet.run_id !== run.id || packet.revision > run.revision || packet.inputs !== hash(JSON.stringify(reviewInputs(run)))) throw new Error('审查交接材料不属于当前运行内容,请重新生成 handoff');
120
- const snapshot = assertSnapshot(root, run, packet.snapshot);
121
- if (isDev(run)) assertValidation(root, req, run, contents);
137
+ const snapshot = assertSnapshot(root, run, packet.snapshot, getSnapshot);
138
+ if (isDev(run)) assertValidation(root, req, run, contents, getSnapshot);
122
139
  if (result?.run_id !== run.id || result.code !== snapshot.digest || result.inputs !== packet.inputs) throw new Error('审查结果的运行、代码版本或交接内容不匹配,请返回本轮审查结果');
123
140
  if (!Array.isArray(result?.findings) || !Array.isArray(result?.coverage?.reviewed) || !Array.isArray(result?.coverage?.uncovered)) throw new Error('审查结果需要 findings 和 coverage.reviewed / uncovered');
124
141
  const covered = [...result.coverage.reviewed, ...result.coverage.uncovered];
@@ -7,8 +7,8 @@ import { parseBranch } from './artifact-model.mjs';
7
7
  import { updateMeta } from './meta-store.mjs';
8
8
  import { loadWorkspace } from './workspace-read.mjs';
9
9
  import { readProfile } from './project.mjs';
10
- import { isDev, applyDevEvidence, assertReview, assertDelivery, receipt } from './run-gates.mjs';
11
- import { codeSnapshot } from './code-snapshot.mjs';
10
+ import { isDev, coreSteps, applyDevEvidence, assertReview, assertDelivery, receipt } from './run-gates.mjs';
11
+ import { codeSnapshot, snapshotReader } from './code-snapshot.mjs';
12
12
 
13
13
  export const FLOWS = {
14
14
  feature: ['Step0', 'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8'],
@@ -160,18 +160,19 @@ export function changeRun(root, { branch, id, revision, input = {}, action = 'sa
160
160
  run.history.push({ at, stage: run.stage, status: 'cancelled', reason: input.reason });
161
161
  } else {
162
162
  applyCheckpoint(run, input, at, action !== 'complete');
163
- applyDevEvidence(root, req, run, input, at);
163
+ const getSnapshot = snapshotReader(root, run);
164
+ applyDevEvidence(root, req, run, input, at, undefined, getSnapshot);
164
165
  if (action === 'complete') {
165
166
  const steps = FLOWS[run.kind];
166
167
  if (run.status !== 'running' || run.stage !== steps.at(-1) || !steps.every((s) => done(run.steps[s].status)) || run.steps[steps.at(-1)].status !== 'completed') throw new Error('还有未完成步骤、待用户决定或阻塞,不能标记已完成');
167
168
  if (['feature', 'bug'].includes(run.kind)) {
168
- const required = run.kind === 'feature' ? ['F4', 'F5', 'F6', 'F7', 'F8'] : ['B4', 'B5'];
169
- assertDelivery(root, req, run);
169
+ const required = coreSteps(run);
170
+ assertDelivery(root, req, run, undefined, getSnapshot);
170
171
  receipt(root, req, run, 'delivery');
171
172
  if (required.some((s) => run.steps[s].status !== 'completed') || run.decision?.action !== 'deliver' || !run.decision.confirmed) throw new Error('完整 dev 流程必须完成方案、实现、验证、审查和交付,且用户已选择交付');
172
173
  }
173
- if (run.kind === 'review') assertReview(root, req, run);
174
- const files = { feature: ['plan.md', 'review.md', 'delivery.md'], bug: ['plan.md', 'review.md', 'delivery.md'], review: ['review.md'], tech: ['tech-doc.md'], release: ['release-doc.md'] };
174
+ if (run.kind === 'review') assertReview(root, req, run, undefined, getSnapshot);
175
+ const files = { feature: ['requirement.md', 'plan.md', 'review.md', 'delivery.md'], bug: ['requirement.md', 'plan.md', 'review.md', 'delivery.md'], review: ['review.md'], tech: ['tech-doc.md'], release: ['release-doc.md'] };
175
176
  for (const name of files[run.kind] ?? []) {
176
177
  const file = path.join(req.abs, name);
177
178
  if (!fs.existsSync(file) || parseBranch(fs.readFileSync(file, 'utf8')) !== branch) throw new Error(`缺少当前分支的产物:${name}`);
@@ -1,10 +1,28 @@
1
- # 内部模块边界与统一读取模型
1
+ # 架构、模块边界与统一读取模型
2
2
 
3
- 安装接入在 `bin/`;各 Skill 的 SKILL.md 与 references 定义流程步骤、确认点和调用时机;`workflow/lib/` 承担共享规则与数据读写;`workflow/scripts/` 保留既有命令和导出入口。数据库、代码图谱、wiki 的执行与凭据仍在各自能力目录。`shared/` 只分发参考文档,运行共享代码随 workflow 的 lib 一起安装。
3
+ 本文对应 0.29.0(2026-10-28),包括独立 nacos-config、需求文档与 dev 显式触发规则;实现以代码与各 skill 的 skill.json 为准。
4
4
 
5
+ ## 安装分发与运行
6
+
7
+ 安装接入在 `bin/`;各 Skill 的 SKILL.md 与 references 定义流程步骤、确认点和调用时机;`workflow/lib/` 承担共享规则与数据读写;`workflow/scripts/` 保留既有命令和导出入口。数据库、代码图谱、wiki、Nacos 的执行与凭据仍在各自能力目录。`shared/` 只分发参考文档,运行共享代码随 workflow 的 lib 一起安装。宿主代理执行规则与命令,workflow-run 不提供常驻的 Agent 调度服务。
8
+
9
+ `bin/skills.mjs` 从各目录的 `skill.json` 发现当前 9 个 skills,以 `requires` 展开必需依赖,`optional` 标记可选协作;`userFiles` 决定升级保留范围,`templates` 声明知识模板,`docnexus` 声明分类。`package.json.files` 决定 npm 分发内容。默认在 `.agents/skills/` 安装完整文件,其他环境逐 skill 建相对链接;`--copy` 或链接失败时改用拷贝。安装清单记录分发文件 hash,手改文件升级前备份,用户配置不覆盖。
10
+
11
+ DocNexus 在安装环节必装,即使只选择 nacos-config 也会接入;Nacos 的读取脚本本身没有 workflow / DocNexus 运行依赖。DocNexus 自带的入口、召回等 skills 单独链接给宿主,不计入本包的 9 个 skills。
12
+
13
+ ## 两条执行路径
14
+
15
+ | 请求 | 调用路径 | 状态归属 |
16
+ |---|---|---|
17
+ | 开发、正式审查、技术 / 上线方案 | 宿主 → 流程 skill → workflow/scripts → workflow/lib;按需调用能力型 skills 或 DocNexus | 正式需求产物与 meta.json;按执行协议记录 runs |
18
+ | 读取 Nacos 参数 | 宿主 → nacos-config → config.mjs → 所选 Nacos 配置接口 | 默认仅返回脱敏快照,不绑定需求、不创建运行、不落盘原文 |
19
+
20
+ dev / project-review 可在已有流程中按需调用 nacos-config,读取结果作为配置证据;独立查询不自动启动完整工作流。能力型 skill 的 SQL、HTTP、CodeGraph 执行逻辑不因共享核心存在而搬进 lib。
5
21
 
6
22
  dev / project-review 的 SKILL.md 只保留触发边界、门禁、步骤路由、必要命令和结果去向。方法细节按阶段保存在各自 references 中,进入阶段前只读对应小节,避免开工加载全部方法。F1~F8、B1~B5 与审查第 1~9 步编号不变;报告选择、快速通道、完成标记等关键约束在入口可见,具体执行仍由阶段说明和共享状态协议约束。
7
23
 
24
+ dev 的入口要求显式流程授权:实际调用 `/dev` / `$dev`、点选 skill 或明确要求 dev / 完整开发工作流。普通分析、修改、修复、测试和 Git 操作不会经 workflow 自动转进 dev;旧运行与绑定也不构成启动授权。Codex 的 `dev/agents/openai.yaml` 关闭隐式调用,skill 本文在任何开工命令前检查入口;安装器把同一边界写进所选环境的项目说明。已授权同任务按阶段续接,当前独立分析 / 提交请求不重启或自行推进阶段。
25
+
8
26
  ## 共享核心
9
27
 
10
28
  | 模块 | 职责 |
@@ -42,12 +60,32 @@ lib 不依赖 scripts;纯模型不依赖 I/O。读侧不调用 sync 或推进
42
60
 
43
61
  ## 能力边界
44
62
 
45
- `lib/capabilities.mjs` 集中探测接入,`resolve.mjs status` 输出本轮能力快照(ready / blockers、通道、模板解析结果),`references/capabilities.md` 定义所有 Skill 共用的失败处理。CodeGraph 的库探测通过其 status 命令交给能力适配器,lib 不导入 Skill 执行脚本。新会话或环境变化时刷新,不持久化个人能力状态到需求元信息。
63
+ `lib/capabilities.mjs` 集中探测接入,`resolve.mjs status` 输出本轮能力快照(ready / blockers、通道、模板解析结果),`references/capabilities.md` 定义依赖 workflow 的 Skill 共用的失败处理。CodeGraph 的库探测通过其 status 命令交给能力适配器,lib 不导入 Skill 执行脚本。新会话或环境变化时刷新,不持久化个人能力状态到需求元信息。
46
64
 
47
65
  DocNexus 是必装组件:安装器缺失即接入,安装失败不报告完成;已有组件默认复用,`--with-docnexus` 强制更新。模板只从知识库读取,包内模板仅用于导入。知识查询失败不作为空结果继续。CodeGraph、wiki、数据库仍按共享规则选择增强通道;必需目标、需求绑定和语句拦截按各自语义处理。
48
66
 
67
+ nacos-config 独立按需读取,不属于 capabilities.mjs 集中探测的通道。`inspect` 仅列本地 application / bootstrap 候选与命名连接;`get` 才验证远端网络、鉴权和指定配置。项目画像 `config_center: nacos` 只说明项目使用的配置中心,不代表已有 Nacos 连接、鉴权通过或运行时配置已核实。
68
+
69
+ `config.mjs` 处理 YAML / properties、本地属性与环境变量占位符、显式 profile、指定文件的覆盖顺序和脱敏输出;YAML 解析依赖装在 nacos-config 目录。连接可来自所选文件,或本机 `config.json` 中的命名连接,两者互斥。配置请求仅 GET,POST 仅用于登录;token 不落盘。输出标明 Namespace、Group、Data ID、时间和内容摘要,不模拟完整 Spring 配置合并、灰度或刷新,也不自动生成数据库连接。协议和字段见 `<skills>/nacos-config/references/connection.md`(该 skill 未安装时不可用)。
70
+
71
+ ## 运行环境与数据位置
72
+
73
+ | 位置 | 保存内容 |
74
+ |---|---|
75
+ | 代理技能目录 | SKILL.md、references、执行脚本和安装清单;连接配置按规则忽略 |
76
+ | workflow/profile.json / profile.local.json | 团队项目事实 / 本机环境与覆盖项,均不放凭据;后者不提交 |
77
+ | .docnexus/ | DocNexus 项目配置、npm 清单、依赖、skills、草稿与索引;内部文件按其 gitignore 管理 |
78
+ | .codegraph/ | 本机代码图谱索引,不提交 |
79
+ | workflow-run/docs/requirements/&lt;需求&gt;/&lt;项目&gt;/ | 正式 Markdown 与需求 meta.json(绑定、产物索引、runs、可恢复收尾待办) |
80
+ | workflow-run/docnexus/ | 团队知识与生效模板;技术 / 上线方案模板首次按用户样例创建 |
81
+ | workflow-run/feedback/、other/、tmp/ | 运行反馈、普通聊天辅助文件、忽略提交的临时文件与锁 |
82
+
83
+ view / report 读取需求工作区快照展示,不触发运行转换或远程配置拉取。DocNexus 的 view 是单独的本地知识浏览服务。远端数据库 / wiki / Nacos 始终是外部数据源,本地产物仅保留任务所需、允许展示的证据。
84
+
49
85
  ## 执行可靠性
50
86
 
87
+ 完整流程在 F3 / B3 收尾先生成 requirement.md,独立记录目标、范围、AC 验收与决定;plan.md 保存实现设计并绑定需求 hash / 版本。需求变化后必须重新收尾方案,旧确认与验证、审查、交付证据失效;只改实现方案不修改需求文档。view / report / PR 引用将需求文档作为独立产物展示。
88
+
51
89
  关键转换由 run-gates 执行,不仅在 complete 检查。方案批准关联具体正文;验证在执行前 snapshot、执行后登记;review-handoff 从已保存事实和代码范围生成交接材料,不传实现者结论。审查结果同时返回报告草稿与结构化 findings/coverage,主 agent 统一收尾,交付选择绑定该轮代码与报告版本。
52
90
 
53
91
  artifact.mjs 在命令层解析知识模板并传入精确草稿检查;artifact-finalize 不导入命令入口。两次带锁写入先登记 pending_finalization,再发布文档并提交索引与运行;meta 中的待办是恢复依据,不另建状态数据库。中断后拒绝其他元信息写入,resume 重查证据并幂等完成,abort 安全还原原文件。只读命令展示待办,不自动修复。快照与阶段协议见 execution.md。
@@ -1,6 +1,6 @@
1
1
  # 开工能力与失败处理
2
2
 
3
- 所有 Skill 共用本规则。开工在项目根运行一次:
3
+ 依赖 workflow 的 Skill 共用本规则。开工在项目根运行一次:
4
4
 
5
5
  ```sh
6
6
  node <skills>/workflow/scripts/resolve.mjs status
@@ -8,6 +8,8 @@ node <skills>/workflow/scripts/resolve.mjs status
8
8
 
9
9
  保留输出作为本轮能力快照;同一项目的流程跳转、子 agent 直接复用,由主 agent 一并交接,可用 workflow-run/tmp/capabilities.json 暂存交接。新会话恢复、切换项目、配置或安装发生变化时重新探测。快照仅本轮使用,不作为团队配置或固定状态写入 meta.json。
10
10
 
11
+ 独立 nacos-config 不要求加载 workflow 或运行本命令,也没有对应的集中能力字段;其 `inspect` 仅检查本地候选,`get` 才验证远端。dev / project-review 内调用它时沿用已有工作流快照,Nacos 读取结果另带配置来源,不据 `profile.config_center` 推断连接可用。
12
+
11
13
  ## 开工门槛
12
14
 
13
15
  `ready` 表示必装组件 DocNexus 已接入;为 false 时先报告 `blockers`,修复后再开始任务。不跳过知识库,不回退到内置模板。status / profile / report / view 等诊断、只读查看与安装修复仍可执行。
@@ -2,9 +2,9 @@
2
2
 
3
3
  完整流程进入方案、实现、验证、审查或交付时读对应小节。快速通道不调用本文的运行与落盘命令。所有命令在业务项目根运行,`<skills>` 为安装目录;JSON 输入文件放 `workflow-run/tmp/`。
4
4
 
5
- ## 方案与实现门禁
5
+ ## 需求、方案与实现门禁
6
6
 
7
- 首次创建运行仍在 F4 / B4,不提前 bind。`scope` 保存审查基线和明确排除范围,缺省取需求 base/画像 main_branch 与 review.exclude:
7
+ 澄清后先按 F4 标准判定规模与通道;完整流程首次创建运行在 F3 / B3 收尾,bind 后先生成独立需求文档。快速通道仍不 bind。`scope` 保存审查基线和明确排除范围,缺省取需求 base/画像 main_branch 与 review.exclude:
8
8
 
9
9
  ```json
10
10
  {"scope":{"base":"main","exclude":["unrelated/**"]}}
@@ -12,6 +12,14 @@
12
12
 
13
13
  完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 sync 代替收尾。模板仍由调用方用 `resolve.mjs template <skill> <id>` 读取:
14
14
 
15
+ ```sh
16
+ node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind requirement --draft workflow-run/tmp/requirement.md --input workflow-run/tmp/checkpoint.json
17
+ ```
18
+
19
+ 需求文档保存背景目标、范围边界、AC 验收标准、已确认决定与待确认问题。功能收尾 checkpoint 标 `{"steps":{"F3":{"status":"completed"}}}`,bug 改为 B3;随后 save stage F4 / B4。M / L 保留原有需求理解确认,不新增重复确认。未收尾 requirement.md 不能完成 F3 / B3 或进入方案。
20
+
21
+ plan.md 头部引用需求文档 cite 与版本,只写实现设计、技术风险、实施步骤和验证计划;验证引用 AC 编号,不复制业务需求。方案收尾自动绑定需求 hash / 版本:
22
+
15
23
  ```sh
16
24
  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
17
25
  ```
@@ -25,6 +33,8 @@ M / L 取得用户实际确认后,用 save 记录 `approval: {"confirmed":true
25
33
 
26
34
  未收尾方案、M / L 未确认、核心步骤 skipped 都会被拒绝。程序校验确认记录与版本,不能替代 agent 核实用户是否真的授权。
27
35
 
36
+ 需求变化回 F3(bug 回 B3)重新澄清并 finalize requirement;程序清除旧方案确认、实现、验证、审查和交付选择,旧方案不能作为新需求的依据。即使方案正文不变,也要在 F4 / B4 重新收尾以绑定新需求版本;M / L 重新取得方案确认。只改实现方式则仅更新 plan,不改 requirement。手动改需求正文而未收尾也会使后续证据校验失败。
37
+
28
38
  ## 验证证据
29
39
 
30
40
  feature 实现完成后 save F5 completed,进入 F6;bug 在 B4 验证。**测试/操作执行前**生成快照:
@@ -60,7 +70,7 @@ result 只接受 passed / failed / unverified;失败或未验证须 reason,
60
70
  node <skills>/workflow/scripts/review-handoff.mjs --id <id> --depth 标准 --capabilities workflow-run/tmp/capabilities.json
61
71
  ```
62
72
 
63
- 输出 `path` 是交接 JSON,位于 tmp/review/<运行id>/。自动汇总项目/skills 路径、实际基线、排除范围、风险分批、验收和已确认决定、方案、验证命令与结果、上次报告及代码快照。没有能力文件时省略参数,主 agent 补交本轮能力快照;不重新探测。只传事实,不传实现者的自审结论。
73
+ 输出 `path` 是交接 JSON,位于 tmp/review/<运行id>/。自动汇总项目/skills 路径、实际基线、排除范围、风险分批、requirement_document(需求文档路径、hash 与版本)、续接事实摘要、方案、验证命令与结果、上次报告及代码快照。验收与业务范围以对应需求文档为准,context 只作缓存摘要。没有能力文件时省略参数,主 agent 补交本轮能力快照;不重新探测。只传事实,不传实现者的自审结论。
64
74
 
65
75
  独立子 agent 按 project-review 第 1~7 步审查,返回报告草稿与结构化结果,主 agent 负责正式收尾并更新同一运行。没有子 agent 时由当前会话同样执行并如实署名。**审查期间不修改被审代码**。JSON 结果结构以 packet.result_schema 为准,run_id / code / inputs 原样回传,以绑定本轮运行、代码版本和交接内容;范围外发现标 scope: outside,不计入本次交付的严重问题门禁。零发现 findings 为空数组,scope.review 中每个文件必须进入 coverage.reviewed 或 uncovered,不能漏报未审文件。
66
76
 
@@ -7,6 +7,7 @@
7
7
  ```
8
8
  workflow-run/docs/requirements/<需求名>/<项目名>/
9
9
  ├── meta.json # 运行记录 runs(阶段、步骤完成标记、等待决定、上下文、完成时间)及 需求名、绑定的分支、各产物(种类、版本、日期、wiki 发布记录、DocNexus 沉淀)
10
+ ├── requirement.md # 需求文档(F3 / B3 收尾;目标、范围、AC 验收与澄清决定)
10
11
  ├── plan.md # 方案(dev,非快速通道都写;S / M 简版;缺陷修复追加修复方案节)
11
12
  ├── delivery.md # 交付说明(dev,完整流程审查后用户选择交付才生成;S 快速通道不落盘)
12
13
  ├── review.md # 审查报告(独立 project-review 或 dev 完整流程的自查;S 快速通道不落盘);复审也写这个文件,上一版归档(见「落盘」)
@@ -42,13 +43,15 @@ node <skills>/workflow/scripts/requirement.mjs which
42
43
 
43
44
  一个需求可以绑定多个分支(`bind` 在其他分支上用同一个名字即可)。
44
45
 
46
+ 完整开发 / 修复的首个文档为 F3 / B3 收尾的 requirement.md,绑定和 start 在此时发生;plan.md 随后记录实现设计与需求版本。需求、方案各自版本化,已有历史文档不自动改写。S 快速通道始终不绑定、不落盘;退出快速通道先补需求文档再补方案。
47
+
45
48
  ## 运行状态
46
49
 
47
50
  完整流程在本文件的 `runs` 中按运行 id 保存进度,关联分支;同一需求可有多次运行。`status: completed` 和 `completed_at` 是本次运行已完成的明确标记,步骤也单独记录 completed。保存/恢复和各 skill 的记录时机见 `runs.md`;快速通道不创建记录。`sync` 只重建产物索引,保留 runs 和其他扩展字段;重新 bind 也不会清空历史。元信息采用原子写入与短时写锁,状态更新另有 revision 检查。
48
51
 
49
52
  ## 落盘
50
53
 
51
- 正式产物先写 `workflow-run/tmp/` 草稿,统一按 [execution.md](execution.md) 用 `artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind <plan|delivery|review|tech|release> --draft <草稿>` 收尾。命令校验当前步骤、分支与知识模板,归档旧版、发布文件、更新索引/版本并登记运行证据;review 还须 packet 与结构化 result,delivery 须本轮有效交付选择。不要直接覆盖正式文件后只 sync。
54
+ 正式产物先写 `workflow-run/tmp/` 草稿,统一按 [execution.md](execution.md) 用 `artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind <requirement|plan|delivery|review|tech|release> --draft <草稿>` 收尾。命令校验当前步骤、分支与知识模板,归档旧版、发布文件、更新索引/版本并登记运行证据;requirement 在 F3 / B3,plan 在 F4 / B4,方案记录依据的需求版本;review 还须 packet 与结构化 result,delivery 须本轮有效交付选择。不要直接覆盖正式文件后只 sync。
52
55
 
53
56
  - 输出 path(相对项目根)、cite(跨文档引用)、previous(上一版归档)、version 和 run。文件名固定,目录只留最新版;文档仓库模式的 cite 为「文档仓库名:仓库内路径」。
54
57
  - 旧版归档在 `workflow-run/tmp/old-artifacts/<需求>/<项目>/<种类>_v<N>.md`,不提交;告诉用户归档了什么,不替用户删除。相同命令重试不重复升级版本或状态。