@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
@@ -37,6 +37,8 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
37
37
 
38
38
  “已完成”表示**本次运行范围已交付**,不是整个需求已经上线。dev 完成后,用户选择的技术方案、上线方案、wiki 发布是同一个 meta.json 中的新运行,不把已完成的 dev 改回未完成。提交、推送和知识沉淀仍按既有授权规则处理,不因 completed 自动执行;这些可选后续动作不阻止已完成的技能交付标记完成。
39
39
 
40
+ 关键门禁、代码快照、自动审查交接和正式文档收尾见 [execution.md](execution.md)。运行创建时机保持不变;方案确认绑定 hash/版本,验证和审查绑定代码快照,交付选择绑定本轮报告。
41
+
40
42
  ## 写 checkpoint
41
43
 
42
44
  完整 dev 开始记录前已经完成的前置步骤,要把对话中确认的事实补入第一份 checkpoint;没有实际完成的步骤不能补成 completed。例如 F4 开始时:
@@ -64,7 +66,7 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
64
66
 
65
67
  每完成一个步骤、发生阻塞、准备等待用户,或结束本轮会话前,save 一次;`context` 按顶层字段合并,列表字段更新时提供完整列表,不写密码、token。每一步可记录 `evidence`(命令、结果、产物路径、未验证原因)和 `note`;这些是已观察到的结果,不得用计划冒充。
66
68
 
67
- 审查报告已交给用户、等待修复或交付时:
69
+ 报告必须先由 artifact.mjs finalize 收尾并登记审查证据;报告已交给用户、等待修复或交付时:
68
70
 
69
71
  ```json
70
72
  {
@@ -79,20 +81,20 @@ node <skills>/workflow/scripts/run.mjs cancel --id <运行id> --expect-revision
79
81
  前面的 F4~F6 必须已按实际进度保存,不能为凑齐示例而直接标完成。bug 的 B5 同时包含审查与交付,报告完成等待选择时 B5 仍为 in_progress,最后交付才标完成。
80
82
 
81
83
  - 用户选修复:save `stage: F5`、`status: running`、`decision: {"action":"fix","confirmed":true}`;bug 回 B4。回到前面的阶段会自动重置该阶段及后续的完成标记、清除旧交付选择,旧 checkpoint 保留在 history;修复、验证和复审后再次等待选择。需求变化需回 F3,规模变化同时写 size。
82
- - 用户明确选交付:save `stage: F8`、`status: running`、`decision: {"action":"deliver","confirmed":true}`;bug 留在 B5。只记录用户实际确认的选择,遗留风险写 context。
84
+ - 用户明确选交付:按 execution.md 核对本轮证据,save `stage: F8`、`status: running`、`decision: {"action":"deliver","confirmed":true}`;bug 留在 B5。只记录用户实际确认的选择,遗留风险写 context。
83
85
  - 等方案确认:`status: waiting_user`,waiting_for 说明待确认方案;方案已写不代表用户已同意。
84
86
  - 环境等阻塞:`status: blocked`、reason 说明原因,保留步骤与 remaining;解除后 save running。
85
87
  - 取消:用 cancel,input 提供 reason,不能用 complete 把取消记成完成。
86
88
 
87
- 交付产物、自检、摘要和反馈已处理后,把最后步骤标 completed,再运行 complete。complete 要求所有步骤 completed 或有原因的 skipped;完整 dev 的方案、实现、验证、审查、交付核心步骤不能跳过,用户必须已选择交付,并有当前分支的 plan.md、review.md、delivery.md。其他文档/审查运行也检查当前分支的对应文件。验证步骤完成可以包含如实记录的“未验证”,不等于所有测试都通过。
89
+ 交付产物、自检、摘要和反馈已处理后,把最后步骤标 completed,再运行 complete。complete 要求所有步骤 completed 或有原因的 skipped;完整 dev 的方案、实现、验证、审查、交付核心步骤在 save 时就不能跳过,用户必须已选择交付,并有本运行已收尾、内容仍匹配且属于当前分支的 plan.md、review.md、delivery.md,以及有效代码与审查证据。独立审查也核对代码快照与报告收尾凭据,其他文档运行检查当前分支的对应文件。验证步骤完成可以包含如实记录的“未验证”,不等于所有测试都通过。
88
90
 
89
91
  complete 不接受待用户确认或 blocked 的运行。还在处理本次已承诺的交付事项时不能提前完成;可选下一步不属于本次运行范围。状态写入具有 revision 检查和短时元信息写锁;版本冲突时重新 show,核对并合并进度,不盲目重试覆盖。写入用 workflow-run/tmp/locks/ 下的短时锁目录(不落在需求目录、不会随产物提交),目录名为元信息相对路径的 SHA-256,避免长中文路径超过文件名限制。每次写入持有唯一的 PID/UUID 标记;只回收超过 30 秒且进程已退出的旧标记,非空锁目录不能删除,释放时也只删除自己的标记。mkdir 后尚未写入标记就崩溃的空目录,过期后同样自动恢复。
90
92
 
91
93
  ## 新会话恢复
92
94
 
93
- 1. 先确认业务项目根和当前工作分支,再 show;多个运行时按用户的任务选 id,不能把其他分支的状态直接套过来。
95
+ 1. 先确认业务项目根和当前工作分支,再 show;若提示 pending_finalization,先按 execution.md 恢复/取消收尾。多个运行时按用户的任务选 id,不能把其他分支的状态直接套过来。
94
96
  2. 读取 context、各步骤状态、waiting_for、reason、history 和关联文档,核对 git 改动、已有产物与证据是否仍适用。记录不是当前代码仍然正确的保证。
95
- 3. 从保存的阶段继续,已完成的有效步骤不重复执行。waiting_user 时先取得对应答复;不能将“继续”直接当成“交付”或接受风险。代码已变化而验证/报告失效时,回退到实现或验证阶段并 save,再验证与复审。
97
+ 3. 从保存的阶段继续,已完成的有效步骤不重复执行。waiting_user 时先取得对应答复;不能将“继续”直接当成“交付”或接受风险。show 的 freshness 会提示代码证据是否仍有效;代码已变化而验证/报告失效时,回退到实现或验证阶段并 save,再验证与复审。
96
98
  4. completed 运行只展示已完成及时间,不自动重启;需要新的工作时 start 新记录。旧需求没有 runs 时明确说明暂无可恢复状态,按文档和代码重建,经核对后再记录,不自动假定已完成。
97
99
 
98
100
  `artifacts.mjs` 的 execution 和 `/workflow status` 使用同一份状态;有未结束运行时 next 优先显示等待、阻塞或当前阶段,不越过修复/交付选择推荐后续动作。`/workflow view` 即使尚无 Markdown 也展示已有运行,包含“已完成”标识和完成时间。
@@ -17,6 +17,7 @@
17
17
  运行:<id / 暂无记录> | 状态:<进行中 / 等待用户 / 受阻 / 已完成 / 已取消> | 当前阶段:<stage>
18
18
  已完成步骤:<steps 中 completed 的名称> | 完成时间:<completed_at / —>
19
19
  等待 / 阻塞:<waiting_for / reason / 无>
20
+ 产物收尾:<pending_finalization 的种类与恢复命令 / 无> | 代码证据:<freshness / 暂未记录>
20
21
  | 环节 | 产物 | wiki |
21
22
  |---|---|---|
22
23
  | 方案 / 交付说明 / 审查报告 / 技术方案 / 上线方案 | <path 或「—」> | <pageId vN 或「未发布」> |
@@ -0,0 +1,39 @@
1
+ #!/usr/bin/env node
2
+ // 正式文档写入入口;草稿在 tmp 中编辑,lint 通过后再发布、登记索引与运行证据。
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import { spawnSync } from 'node:child_process';
6
+ import { fileURLToPath } from 'node:url';
7
+ import { resolveTemplate, skillMeta } from './resolve.mjs';
8
+ import { lint } from './lint-doc.mjs';
9
+ import { ARTIFACT_TEMPLATES, finalizeArtifact, resumeFinalization, abortFinalization } from '../lib/artifact-finalize.mjs';
10
+
11
+ export function main(argv) {
12
+ try {
13
+ const args = [...argv]; const action = args.shift(); const opts = {};
14
+ while (args.length) {
15
+ const key = args.shift();
16
+ if (!['--root', '--branch', '--id', '--expect-revision', '--kind', '--draft', '--input', '--packet', '--result'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
17
+ opts[key.slice(2)] = args.shift();
18
+ }
19
+ const root = path.resolve(opts.root ?? '.');
20
+ const branch = opts.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
21
+ const read = (p) => p ? JSON.parse(fs.readFileSync(p === '-' ? 0 : path.resolve(root, p), 'utf8')) : undefined;
22
+ let out;
23
+ if (action === 'resume') out = resumeFinalization(root, { branch, id: opts.id });
24
+ else if (action === 'abort') out = abortFinalization(root, { branch, id: opts.id });
25
+ else if (action === 'finalize') {
26
+ const [skill, template] = ARTIFACT_TEMPLATES[opts.kind] ?? [];
27
+ if (!skill || !opts.draft) throw new Error('finalize 需要 --kind plan|review|delivery|tech|release 和 --draft <草稿.md>');
28
+ const resolved = resolveTemplate(root, skill, template);
29
+ if (!resolved.ok) throw new Error(resolved.hint ?? JSON.stringify(resolved));
30
+ const source = fs.readFileSync(path.resolve(root, resolved.path), 'utf8');
31
+ const rules = skillMeta(skill).templates.find((t) => t.id === template).lint;
32
+ out = finalizeArtifact(root, { branch, id: opts.id, revision: Number(opts['expect-revision']), kind: opts.kind,
33
+ text: fs.readFileSync(path.resolve(root, opts.draft), 'utf8'), input: read(opts.input) ?? {}, packet: read(opts.packet), result: read(opts.result) }, (text) => lint(text, source, rules));
34
+ } else throw new Error('用法:artifact.mjs finalize --id <id> --expect-revision <n> --kind <种类> --draft <草稿> [--input <checkpoint.json>] [--packet <handoff.json> --result <审查结果.json>] | resume --id <id> | abort --id <id>');
35
+ console.log(JSON.stringify(out, null, 2)); return 0;
36
+ } catch (e) { console.error(e.message); return 1; }
37
+ }
38
+ const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
39
+ if (invoked) process.exit(main(process.argv.slice(2)));
@@ -0,0 +1,59 @@
1
+ #!/usr/bin/env node
2
+ // 只交接事实与证据,不交接实现者自审结论;生成过程不推进运行。
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import { spawnSync } from 'node:child_process';
6
+ import { fileURLToPath } from 'node:url';
7
+ import { readRun } from '../lib/runs.mjs';
8
+ import { readProfile } from '../lib/project.mjs';
9
+ import { codeSnapshot, assertSnapshot, hash } from '../lib/code-snapshot.mjs';
10
+ import { isDev, assertValidation, reviewInputs } from '../lib/run-gates.mjs';
11
+ import { scope } from './review-scope.mjs';
12
+
13
+ export function handoff(root, { branch, id, depth = '标准', capabilities = null }) {
14
+ const { req, run } = readRun(root, branch, id);
15
+ if (!['feature', 'bug', 'review'].includes(run.kind) || ['completed', 'cancelled'].includes(run.status)) throw new Error('只有进行中的开发/审查运行可生成交接材料');
16
+ if (req.meta.pending_finalization) throw new Error('先恢复待完成的产物收尾');
17
+ if (isDev(run)) {
18
+ if (run.stage !== (run.kind === 'feature' ? 'F7' : 'B5')) throw new Error('请先完成验证并进入审查阶段');
19
+ assertValidation(root, req, run);
20
+ }
21
+ if (!['快审', '标准', '深审'].includes(depth)) throw new Error('审查深度须为快审 / 标准 / 深审');
22
+ const snapshot = codeSnapshot(root, run);
23
+ const reviewScope = scope(root, { base: run.scope?.base ?? 'main', exclude: run.scope?.exclude ?? [] });
24
+ if (!reviewScope.ok) throw new Error(reviewScope.error);
25
+ assertSnapshot(root, run, snapshot);
26
+ const profile = readProfile(root).profile;
27
+ const inputs = reviewInputs(run);
28
+ return {
29
+ run_id: id, revision: run.revision, project_root: path.resolve(root), skills: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..'),
30
+ branch, depth, snapshot, inputs: hash(JSON.stringify(inputs)), scope: reviewScope, requirement: req.name, facts: inputs.facts,
31
+ plan: run.artifacts?.plan ?? null, previous_report: run.artifacts?.review ?? null,
32
+ validation: run.validation ?? null,
33
+ commands: Object.fromEntries(['main_branch', 'build', 'test', 'test_single', 'lint'].map((k) => [k, profile?.[k] ?? null])),
34
+ capabilities,
35
+ result_schema: { run_id: id, code: snapshot.digest, inputs: hash(JSON.stringify(inputs)), findings: [{ id: '唯一编号', severity: 'CRITICAL|HIGH|MEDIUM|LOW', verification: 'confirmed|pending', scope: 'in_scope|outside(范围外发现单列)', file: '真实路径', line: 1, summary: '触发条件与影响' }], coverage: { reviewed: ['已审文件'], uncovered: ['未审文件'] } },
36
+ rules: '独立读代码,按 project-review 第 1~7 步审查;返回报告草稿和结构化结果,不改代码、不生成 delivery.md、不提交、不另建运行;主 agent 负责 finalize。零发现 findings 为空数组,scope.review 中每个文件必须进入 reviewed 或 uncovered。',
37
+ };
38
+ }
39
+
40
+ export function main(argv) {
41
+ try {
42
+ const args = [...argv]; const opts = {};
43
+ while (args.length) {
44
+ const key = args.shift();
45
+ if (!['--root', '--branch', '--id', '--depth', '--capabilities'].includes(key) || !args.length) throw new Error(`未知或缺少值的参数:${key}`);
46
+ opts[key.slice(2)] = args.shift();
47
+ }
48
+ const root = path.resolve(opts.root ?? '.');
49
+ const branch = opts.branch ?? spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim();
50
+ const capabilities = opts.capabilities ? JSON.parse(fs.readFileSync(path.resolve(root, opts.capabilities), 'utf8')) : null;
51
+ const packet = handoff(root, { branch, id: opts.id, depth: opts.depth, capabilities });
52
+ const file = path.join(root, 'workflow-run/tmp/review', packet.run_id, 'handoff.json');
53
+ fs.mkdirSync(path.dirname(file), { recursive: true });
54
+ fs.writeFileSync(file, `${JSON.stringify(packet, null, 2)}\n`);
55
+ console.log(JSON.stringify({ ok: true, path: path.relative(root, file).split(path.sep).join('/'), packet }, null, 2)); return 0;
56
+ } catch (e) { console.error(e.message); return 1; }
57
+ }
58
+ const invoked = process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
59
+ if (invoked) process.exit(main(process.argv.slice(2)));
@@ -24,27 +24,8 @@ import { resolveTemplate } from './resolve.mjs';
24
24
  const git = (root, args) => spawnSync('git', ['-c', 'core.quotepath=false', ...args], { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
25
25
  const toPosix = (p) => p.split(path.sep).join('/');
26
26
 
27
- // ---------------------------------------------------------------- glob
28
- // ** 跨目录、* 不跨 /、? 单个字符、{a,b} 展开(括号里同样支持这些写法);不含 / 的模式匹配文件名(同 .gitignore)。不区分大小写。
29
- // 没有闭合的 { 按普通字符处理(画像里写错也不会卡住)
30
- function globSource(glob) {
31
- let re = '';
32
- for (let i = 0; i < glob.length; i++) {
33
- const c = glob[i];
34
- const end = c === '{' ? glob.indexOf('}', i) : -1;
35
- if (c === '*' && glob[i + 1] === '*') {
36
- const slash = glob[i + 2] === '/';
37
- re += slash ? '(?:.*/)?' : '.*';
38
- i += slash ? 2 : 1;
39
- } else if (c === '*') re += '[^/]*';
40
- else if (c === '?') re += '[^/]';
41
- else if (end > i) { re += `(?:${glob.slice(i + 1, end).split(',').map(globSource).join('|')})`; i = end; }
42
- else re += c.replace(/[.+^$(){}|[\]\\]/g, '\\$&');
43
- }
44
- return re;
45
- }
46
- export const globToRegExp = (glob) => new RegExp(`^${globSource(glob)}$`, 'i');
47
- export const matchGlob = (p, glob) => globToRegExp(glob).test(glob.includes('/') ? p : p.split('/').pop());
27
+ import { matchGlob } from '../lib/path-match.mjs';
28
+ export { matchGlob, globToRegExp } from '../lib/path-match.mjs';
48
29
  const matchAny = (p, globs = []) => globs.find((g) => matchGlob(p, g)) ?? null;
49
30
 
50
31
  // ---------------------------------------------------------------- 跳过规则
@@ -5,7 +5,8 @@ import path from 'node:path';
5
5
  import { spawnSync } from 'node:child_process';
6
6
  import { fileURLToPath } from 'node:url';
7
7
 
8
- import { STATUS_LABELS, runState, startRun, changeRun } from '../lib/runs.mjs';
8
+ import { runState, startRun, changeRun, readRun } from '../lib/runs.mjs';
9
+ import { codeSnapshot } from '../lib/code-snapshot.mjs';
9
10
  export { FLOWS, STATUS_LABELS, allRuns, branchRuns, runState, startRun, changeRun } from '../lib/runs.mjs';
10
11
  const branchOf = (root) => spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], { cwd: root, encoding: 'utf8' }).stdout?.trim() || null;
11
12
 
@@ -22,13 +23,10 @@ function main(argv) {
22
23
  const input = opts.input ? JSON.parse(fs.readFileSync(opts.input === '-' ? 0 : path.resolve(root, opts.input), 'utf8')) : {};
23
24
  let out;
24
25
  if (action === 'show') {
25
- out = runState(root, branch);
26
- if (opts.id) {
27
- out.current = out.runs.find((r) => r.id === opts.id) ?? null;
28
- if (!out.current) throw new Error('当前分支没有这个运行');
29
- out.next = `${STATUS_LABELS[out.current.status]}:${out.current.stage}(${out.current.id})`;
30
- }
31
- } else if (action === 'start') out = startRun(root, { branch, kind: opts.kind, size: opts.size, input, dir: opts.dir });
26
+ out = runState(root, branch, undefined, opts.id);
27
+ if (opts.id && !out.current) throw new Error('当前分支没有这个运行');
28
+ } else if (action === 'snapshot') out = { ok: true, snapshot: codeSnapshot(root, readRun(root, branch, opts.id).run) };
29
+ else if (action === 'start') out = startRun(root, { branch, kind: opts.kind, size: opts.size, input, dir: opts.dir });
32
30
  else out = changeRun(root, { branch, id: opts.id, revision: opts['expect-revision'] === undefined ? null : Number(opts['expect-revision']), input, action });
33
31
  console.log(JSON.stringify(out, null, 2)); return 0;
34
32
  } catch (e) { console.error(e.message); return 1; }
@@ -237,7 +237,7 @@ function runBlock(r) {
237
237
  if (!r.runs?.length) return '';
238
238
  const labels = { running: '进行中', waiting_user: '等待用户', blocked: '受阻', completed: '已完成', cancelled: '已取消' };
239
239
  const stepLabels = { pending: '未开始', in_progress: '进行中', completed: '已完成', skipped: '已跳过' };
240
- return '<section class="block"><h3>流程运行状态</h3><table><thead><tr><th>运行 / 分支</th><th>阶段</th><th>状态</th><th>步骤进度</th><th>等待 / 阻塞 / 完成时间</th></tr></thead><tbody>' + r.runs.map((run) => '<tr><td>' + esc(run.project + ' · ' + run.kind + ' · ' + run.id) + '<br>' + esc(run.branch) + '</td><td>' + esc(run.stage) + '</td><td>' + esc(labels[run.status] ?? run.status) + '</td><td>' + Object.entries(run.steps).map(([name, s]) => esc(name + ':' + (stepLabels[s.status] ?? s.status))).join('<br>') + '</td><td>' + esc(run.waiting_for ?? run.reason ?? run.completed_at ?? '') + '</td></tr>').join('') + '</tbody></table></section>';
240
+ return '<section class="block"><h3>流程运行状态</h3><table><thead><tr><th>运行 / 分支</th><th>阶段</th><th>状态</th><th>步骤进度</th><th>等待 / 阻塞 / 完成时间</th></tr></thead><tbody>' + r.runs.map((run) => '<tr><td>' + esc(run.project + ' · ' + run.kind + ' · ' + run.id) + '<br>' + esc(run.branch) + '</td><td>' + esc(run.stage) + '</td><td>' + esc(labels[run.status] ?? run.status) + '</td><td>' + Object.entries(run.steps).map(([name, s]) => esc(name + ':' + (stepLabels[s.status] ?? s.status))).join('<br>') + '</td><td>' + esc(run.pending_finalization ? '待恢复产物收尾:' + run.pending_finalization.kind + '(artifact.mjs resume --id ' + run.id + ')' : run.waiting_for ?? run.reason ?? run.completed_at ?? '') + '</td></tr>').join('') + '</tbody></table></section>';
241
241
  }
242
242
 
243
243
  function knowledgeBlock(r) {