@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.
- package/CHANGELOG.md +8 -0
- package/README.md +9 -1
- package/create-release-md-doc/SKILL.md.tpl +3 -5
- package/create-tech-md-doc/SKILL.md.tpl +3 -5
- package/dev/SKILL.md.tpl +8 -8
- package/dev/references/bug.md +3 -1
- package/dev/references/delivery-template.md +1 -1
- package/dev/references/delivery.md +9 -7
- package/dev/references/implementation.md +4 -0
- package/dev/references/plan-template.md +1 -1
- package/dev/references/planning.md +2 -2
- package/dev/references/preflight.md +2 -2
- package/package.json +1 -1
- package/project-review/SKILL.md.tpl +3 -3
- package/project-review/references/reporting.md +8 -8
- package/workflow/SKILL.md.tpl +1 -0
- package/workflow/lib/artifact-finalize.mjs +144 -0
- package/workflow/lib/code-snapshot.mjs +55 -0
- package/workflow/lib/meta-store.mjs +4 -2
- package/workflow/lib/path-match.mjs +21 -0
- package/workflow/lib/requirements.mjs +12 -7
- package/workflow/lib/run-gates.mjs +136 -0
- package/workflow/lib/runs.mjs +56 -12
- package/workflow/lib/workspace-read.mjs +3 -1
- package/workflow/references/architecture.md +10 -0
- package/workflow/references/capabilities.md +1 -1
- package/workflow/references/execution.md +95 -0
- package/workflow/references/requirements.md +12 -13
- package/workflow/references/runs.md +7 -5
- package/workflow/references/status.md +1 -0
- package/workflow/scripts/artifact.mjs +39 -0
- package/workflow/scripts/review-handoff.mjs +59 -0
- package/workflow/scripts/review-scope.mjs +2 -21
- package/workflow/scripts/run.mjs +6 -8
- package/workflow/scripts/view.mjs +1 -1
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
// 证据绑定到 Git 基线、HEAD 及工作区内容;不输出文件正文,也不把工作流自己的产出算作代码变化。
|
|
2
|
+
import fs from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { spawnSync } from 'node:child_process';
|
|
5
|
+
import { createHash } from 'node:crypto';
|
|
6
|
+
import { matchGlob } from './path-match.mjs';
|
|
7
|
+
|
|
8
|
+
export const hash = (value) => createHash('sha256').update(value).digest('hex');
|
|
9
|
+
const INTERNAL = ['workflow-run/**', '.docnexus/**', '.codegraph/**', '.agents/skills/**', '.claude/skills/**', '.qwen/skills/**', '.codebuddy/skills/**'];
|
|
10
|
+
const git = (root, args, encoding = 'utf8') => {
|
|
11
|
+
const r = spawnSync('git', args, { cwd: root, encoding, maxBuffer: 256 * 1024 * 1024 });
|
|
12
|
+
if (r.status !== 0) throw new Error(`代码快照失败:git ${args[0]}:${r.stderr?.toString().trim() || r.error?.message}`);
|
|
13
|
+
return r.stdout;
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
export function assertWorkingBranch(root, run) {
|
|
17
|
+
const top = git(root, ['rev-parse', '--show-toplevel']).trim();
|
|
18
|
+
if (fs.realpathSync.native(top) !== fs.realpathSync.native(root)) throw new Error('请在业务 Git 项目根生成证据');
|
|
19
|
+
const branch = git(root, ['symbolic-ref', '--short', 'HEAD']).trim();
|
|
20
|
+
if (branch !== run.branch) throw new Error('代码快照必须在运行所属的实际工作分支生成,请先切换分支');
|
|
21
|
+
return branch;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export function codeSnapshot(root, run) {
|
|
25
|
+
const branch = assertWorkingBranch(root, run);
|
|
26
|
+
const head = git(root, ['rev-parse', 'HEAD']).trim();
|
|
27
|
+
const base = run.scope?.base || 'main';
|
|
28
|
+
const baseCommit = git(root, ['rev-parse', '--verify', `${base}^{commit}`]).trim();
|
|
29
|
+
const mergeBase = git(root, ['merge-base', baseCommit, head]).trim();
|
|
30
|
+
const exclude = [...INTERNAL, ...(run.scope?.exclude ?? [])];
|
|
31
|
+
const names = new Set([
|
|
32
|
+
...git(root, ['ls-files', '--cached', '--others', '--exclude-standard', '-z']).split('\0'),
|
|
33
|
+
...git(root, ['ls-tree', '-r', '--name-only', '-z', mergeBase]).split('\0'),
|
|
34
|
+
].filter((p) => p && !exclude.some((g) => matchGlob(p, g))));
|
|
35
|
+
const entries = [...names].sort().map((file) => {
|
|
36
|
+
const abs = path.join(root, file);
|
|
37
|
+
let stat;
|
|
38
|
+
try { stat = fs.lstatSync(abs); } catch (e) { if (e.code === 'ENOENT') return [file, 'deleted']; throw e; }
|
|
39
|
+
if (stat.isSymbolicLink()) return [file, 'symlink', fs.readlinkSync(abs)];
|
|
40
|
+
// dirty 标记不能代表具体内容;脏子模块须先处理,不能复用含糊的证据。
|
|
41
|
+
if (stat.isDirectory()) {
|
|
42
|
+
if (git(abs, ['status', '--porcelain', '--untracked-files=all']).trim()) throw new Error(`子模块/嵌套仓库有未提交内容,先处理后生成快照:${file}`);
|
|
43
|
+
return [file, 'submodule', git(abs, ['rev-parse', 'HEAD']).trim()];
|
|
44
|
+
}
|
|
45
|
+
return [file, stat.mode & 0o111 ? 'executable' : 'file', hash(fs.readFileSync(abs))];
|
|
46
|
+
});
|
|
47
|
+
const snapshot = { branch, base, base_commit: baseCommit, merge_base: mergeBase, head, scope: run.scope, files: entries.length };
|
|
48
|
+
return { ...snapshot, digest: hash(JSON.stringify({ ...snapshot, entries })) };
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export function assertSnapshot(root, run, snapshot) {
|
|
52
|
+
const current = codeSnapshot(root, run);
|
|
53
|
+
if (!snapshot?.digest || snapshot.digest !== current.digest) throw new Error('代码或基线已变化,原验证/审查证据已失效;重新生成快照、验证并审查');
|
|
54
|
+
return current;
|
|
55
|
+
}
|
|
@@ -92,13 +92,15 @@ function acquire(lock) {
|
|
|
92
92
|
throw busy(lock);
|
|
93
93
|
}
|
|
94
94
|
|
|
95
|
-
export function updateMeta(file, update, { root = process.cwd() } = {}) {
|
|
95
|
+
export function updateMeta(file, update, { root = process.cwd(), allowFinalization = false } = {}) {
|
|
96
96
|
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
97
97
|
const lock = lockPath(root, file);
|
|
98
98
|
const release = acquire(lock);
|
|
99
99
|
const tmp = path.join(path.dirname(lock), `${path.basename(file)}.${randomUUID()}.tmp`);
|
|
100
100
|
try {
|
|
101
|
-
const
|
|
101
|
+
const current = readMeta(file);
|
|
102
|
+
if (current.pending_finalization && !allowFinalization) throw new Error(`产物收尾尚未完成,先运行 artifact.mjs resume --id ${current.pending_finalization.run_id}`);
|
|
103
|
+
const next = update(current);
|
|
102
104
|
const text = `${JSON.stringify(next, null, 2)}\n`;
|
|
103
105
|
if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== text) {
|
|
104
106
|
fs.writeFileSync(tmp, text);
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
// ---------------------------------------------------------------- glob
|
|
2
|
+
// ** 跨目录、* 不跨 /、? 单个字符、{a,b} 展开(括号里同样支持这些写法);不含 / 的模式匹配文件名(同 .gitignore)。不区分大小写。
|
|
3
|
+
// 没有闭合的 { 按普通字符处理(画像里写错也不会卡住)
|
|
4
|
+
function globSource(glob) {
|
|
5
|
+
let re = '';
|
|
6
|
+
for (let i = 0; i < glob.length; i++) {
|
|
7
|
+
const c = glob[i];
|
|
8
|
+
const end = c === '{' ? glob.indexOf('}', i) : -1;
|
|
9
|
+
if (c === '*' && glob[i + 1] === '*') {
|
|
10
|
+
const slash = glob[i + 2] === '/';
|
|
11
|
+
re += slash ? '(?:.*/)?' : '.*';
|
|
12
|
+
i += slash ? 2 : 1;
|
|
13
|
+
} else if (c === '*') re += '[^/]*';
|
|
14
|
+
else if (c === '?') re += '[^/]';
|
|
15
|
+
else if (end > i) { re += `(?:${glob.slice(i + 1, end).split(',').map(globSource).join('|')})`; i = end; }
|
|
16
|
+
else re += c.replace(/[.+^$(){}|[\]\\]/g, '\\$&');
|
|
17
|
+
}
|
|
18
|
+
return re;
|
|
19
|
+
}
|
|
20
|
+
export const globToRegExp = (glob) => new RegExp(`^${globSource(glob)}$`, 'i');
|
|
21
|
+
export const matchGlob = (p, glob) => globToRegExp(glob).test(glob.includes('/') ? p : p.split('/').pop());
|
|
@@ -22,6 +22,15 @@ export const OLD_DIR = `${TMP_DIR}/old-artifacts`;
|
|
|
22
22
|
const archivePath = (root, dirAbs, kind, v) => path.join(root, OLD_DIR, path.relative(path.join(root, REQ_DIR), dirAbs), `${FILES[kind]}_v${v}.md`);
|
|
23
23
|
const versionsOf = (dirAbs) => readJson(path.join(dirAbs, 'meta.json'))?.versions ?? {};
|
|
24
24
|
|
|
25
|
+
export function indexArtifacts(dir, versions = {}) {
|
|
26
|
+
return fs.readdirSync(dir).map((name) => {
|
|
27
|
+
const p = parseFile(name);
|
|
28
|
+
if (!p) return null;
|
|
29
|
+
const text = fs.readFileSync(path.join(dir, name), 'utf8');
|
|
30
|
+
return { kind: p.kind, version: name === `${FILES[p.kind]}.md` ? versions[p.kind] ?? 1 : p.version, file: name, branch: parseBranch(text), date: headerDate(text), wiki: parseWiki(text), docnexus: parseDocnexus(text) };
|
|
31
|
+
}).filter(Boolean).sort((a, b) => Object.keys(FILES).indexOf(a.kind) - Object.keys(FILES).indexOf(b.kind) || a.version - b.version);
|
|
32
|
+
}
|
|
33
|
+
|
|
25
34
|
// 按目录里的文件重建 meta.json(保留需求名、分支、创建时间)
|
|
26
35
|
// bump:写完新版后(sync <path>)确认新版本——和 path 时归档的上一版副本内容不同就把版本号加一,返回归档了哪些
|
|
27
36
|
export function sync(root, dirRel, { bump = false } = {}) {
|
|
@@ -40,12 +49,7 @@ export function sync(root, dirRel, { bump = false } = {}) {
|
|
|
40
49
|
archived.push({ kind, version: v, file: relOf(root, arc) });
|
|
41
50
|
}
|
|
42
51
|
}
|
|
43
|
-
const artifacts =
|
|
44
|
-
const p = parseFile(name);
|
|
45
|
-
if (!p) return null;
|
|
46
|
-
const text = fs.readFileSync(path.join(dir, name), 'utf8');
|
|
47
|
-
return { kind: p.kind, version: name === `${FILES[p.kind]}.md` ? versions[p.kind] ?? 1 : p.version, file: name, branch: parseBranch(text), date: headerDate(text), wiki: parseWiki(text), docnexus: parseDocnexus(text) };
|
|
48
|
-
}).filter(Boolean).sort((a, b) => Object.keys(FILES).indexOf(a.kind) - Object.keys(FILES).indexOf(b.kind) || a.version - b.version);
|
|
52
|
+
const artifacts = indexArtifacts(dir, versions);
|
|
49
53
|
const branches = old.branches ?? []; // 绑定只由 bind 更新;文档头不隐式修改需求归属。
|
|
50
54
|
const latest = Object.fromEntries(Object.keys(FILES).map((k) => [k, artifacts.filter((a) => a.kind === k).at(-1)?.file ?? null]));
|
|
51
55
|
// 内容没变就不写(meta.json 随需求目录提交,避免无谓的改动);产物有变化才更新 updated
|
|
@@ -67,7 +71,7 @@ export function which(root, branch) {
|
|
|
67
71
|
if (!L.ok) return notReady(L);
|
|
68
72
|
const r = find(root, branch, L);
|
|
69
73
|
const where = L.mode === 'repo' ? { mode: 'repo', repo: L.repo_rel, project: L.project } : { mode: 'project', project: L.project };
|
|
70
|
-
if (r) return { bound: true, ...where, branch, name: r.name, dir: r.dir, meta: sync(root, r.dir) };
|
|
74
|
+
if (r) return { bound: true, ...where, branch, name: r.name, dir: r.dir, meta: r.meta.pending_finalization ? r.meta : sync(root, r.dir) };
|
|
71
75
|
const recent = requirements(root, L).sort((a, b) => String(b.updated).localeCompare(String(a.updated))).slice(0, 5).map(({ name, dir, branches, updated }) => ({ name, dir, branches, updated }));
|
|
72
76
|
// 其他项目已有的需求(跨服务需求,本项目可以用同一个名字加入);文档仓库里常见,随代码提交时一般没有
|
|
73
77
|
const mine = new Set(requirements(root, L).map((x) => x.slug));
|
|
@@ -118,6 +122,7 @@ export function nextPath(root, kind, branch) {
|
|
|
118
122
|
if (!L.ok) return { code: 2, out: notReady(L) };
|
|
119
123
|
const r = find(root, branch, L);
|
|
120
124
|
if (!r) return { code: 2, out: { ok: false, ...which(root, branch) } };
|
|
125
|
+
if (r.meta.pending_finalization) return { code: 1, out: { ok: false, hint: `产物收尾尚未完成,先运行 artifact.mjs resume --id ${r.meta.pending_finalization.run_id}` } };
|
|
121
126
|
const abs = path.join(r.abs, `${FILES[kind]}.md`);
|
|
122
127
|
let v = 1; let previous = null; let record = null;
|
|
123
128
|
if (fs.existsSync(abs)) {
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
// dev 的关键门禁与证据约束;不执行测试,也不代替用户作确认。
|
|
2
|
+
import fs from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { FILES, parseBranch } from './artifact-model.mjs';
|
|
5
|
+
import { hash, assertSnapshot, assertWorkingBranch } from './code-snapshot.mjs';
|
|
6
|
+
|
|
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'];
|
|
9
|
+
|
|
10
|
+
export function receipt(root, req, run, kind, contents = {}) {
|
|
11
|
+
const record = run.artifacts?.[kind];
|
|
12
|
+
const file = path.join(req.abs, `${FILES[kind]}.md`);
|
|
13
|
+
const text = contents[kind] ?? (fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null);
|
|
14
|
+
if (!record || text === null || record.hash !== hash(text) || parseBranch(text) !== run.branch) throw new Error(`缺少本次运行已收尾的当前分支产物,或内容已变化:${FILES[kind]}.md;请运行 artifact.mjs finalize`);
|
|
15
|
+
return record;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export function assertPlan(root, req, run, contents) {
|
|
19
|
+
assertWorkingBranch(root, run);
|
|
20
|
+
const plan = receipt(root, req, run, 'plan', contents);
|
|
21
|
+
if (run.size !== 'S' && (run.plan_approval?.hash !== plan.hash || run.plan_approval.version !== plan.version)) throw new Error('M / L 方案尚未由用户确认,或确认后方案已变化;先记录 approval.confirmed');
|
|
22
|
+
return plan;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export function assertValidation(root, req, run, contents) {
|
|
26
|
+
const plan = assertPlan(root, req, run, contents);
|
|
27
|
+
if (run.implementation?.plan !== plan.hash) throw new Error('尚未通过方案门禁进入实现,请先进入 F5;bug 保存 implement: true');
|
|
28
|
+
assertSnapshot(root, run, run.validation?.snapshot);
|
|
29
|
+
return run.validation;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function assertReview(root, req, run, contents) {
|
|
33
|
+
const validation = isDev(run) ? assertValidation(root, req, run, contents) : null;
|
|
34
|
+
const report = receipt(root, req, run, 'review', contents);
|
|
35
|
+
if (!run.review || run.review.report_hash !== report.hash || run.review.report_version !== report.version
|
|
36
|
+
|| run.review.inputs !== hash(JSON.stringify(reviewInputs(run)))
|
|
37
|
+
|| (validation && run.review.snapshot.digest !== validation.snapshot.digest)) throw new Error('缺少对应本轮验证和报告版本的审查证据,请重新审查');
|
|
38
|
+
if (!validation) assertSnapshot(root, run, run.review.snapshot);
|
|
39
|
+
return run.review;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export function assertDelivery(root, req, run, contents) {
|
|
43
|
+
const review = assertReview(root, req, run, contents);
|
|
44
|
+
const decision = run.decision;
|
|
45
|
+
if (decision?.action !== 'deliver' || decision.confirmed !== true || decision.report_hash !== review.report_hash
|
|
46
|
+
|| decision.report_version !== review.report_version || decision.code !== review.snapshot.digest) throw new Error('进入交付前必须由用户明确选择本轮报告的交付;旧交付选择不再有效');
|
|
47
|
+
const serious = review.result.findings.filter((f) => f.scope !== 'outside' && ['CRITICAL', 'HIGH'].includes(f.severity) && f.verification === 'confirmed');
|
|
48
|
+
if (serious.some((f) => !decision.accepted_risks?.includes(f.id))) throw new Error('严重遗留风险必须逐项说明并取得用户明确接受,记录 accepted_risks 中的问题 id');
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export function applyDevEvidence(root, req, run, patch, at, contents = {}) {
|
|
52
|
+
if (!isDev(run)) return;
|
|
53
|
+
for (const step of coreSteps(run)) if (run.steps[step].status === 'skipped') throw new Error(`完整 dev 核心步骤不能跳过:${step}`);
|
|
54
|
+
if (patch.approval !== undefined) {
|
|
55
|
+
if (patch.approval?.confirmed !== true) throw new Error('approval 必须记录用户明确确认:confirmed: true');
|
|
56
|
+
const plan = receipt(root, req, run, 'plan', contents);
|
|
57
|
+
run.plan_approval = { hash: plan.hash, version: plan.version, at };
|
|
58
|
+
}
|
|
59
|
+
const implementing = patch.implement === true || (run.kind === 'feature' && patch.stage === 'F5');
|
|
60
|
+
if (patch.implement !== undefined && patch.implement !== true) throw new Error('implement 只接受 true');
|
|
61
|
+
if (implementing) {
|
|
62
|
+
if (run.kind === 'feature' && run.steps.F4.status !== 'completed') throw new Error('方案步骤 F4 尚未完成,不能进入实现');
|
|
63
|
+
if (run.kind === 'bug' && run.stage !== 'B4') throw new Error('bug 只能在 B4 进入实现');
|
|
64
|
+
const plan = assertPlan(root, req, run, contents);
|
|
65
|
+
run.implementation = { plan: plan.hash, at };
|
|
66
|
+
}
|
|
67
|
+
if (patch.validation !== undefined) {
|
|
68
|
+
if (run.stage !== (run.kind === 'feature' ? 'F6' : 'B4')) throw new Error('请在 F6/B4 验证阶段记录 validation');
|
|
69
|
+
const plan = assertPlan(root, req, run, contents);
|
|
70
|
+
if (run.implementation?.plan !== plan.hash) throw new Error('先通过方案门禁进入实现,再记录验证');
|
|
71
|
+
const v = patch.validation;
|
|
72
|
+
if (!Array.isArray(v?.checks) || !v.checks.length || v.checks.some((c) => !c.command?.trim()
|
|
73
|
+
|| !['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);
|
|
75
|
+
run.validation = { snapshot, checks: v.checks, at };
|
|
76
|
+
run.review = null; run.decision = null;
|
|
77
|
+
if (run.kind === 'feature') for (const step of ['F7', 'F8']) run.steps[step] = { status: 'pending' };
|
|
78
|
+
}
|
|
79
|
+
if (patch.decision?.action === 'deliver') {
|
|
80
|
+
if (run.kind === 'feature' && run.steps.F7.status !== 'completed') throw new Error('审查步骤 F7 尚未完成,不能选择交付');
|
|
81
|
+
const review = assertReview(root, req, run, contents);
|
|
82
|
+
run.decision = { ...run.decision, code: review.snapshot.digest, report_hash: review.report_hash, report_version: review.report_version };
|
|
83
|
+
assertDelivery(root, req, run, contents);
|
|
84
|
+
}
|
|
85
|
+
const completed = (s) => patch.steps?.[s]?.status === 'completed';
|
|
86
|
+
if (run.kind === 'feature') {
|
|
87
|
+
if (completed('F4')) receipt(root, req, run, 'plan', contents);
|
|
88
|
+
if (patch.stage === 'F6' || completed('F5')) {
|
|
89
|
+
const plan = assertPlan(root, req, run, contents);
|
|
90
|
+
if (run.implementation?.plan !== plan.hash) throw new Error('尚未通过方案门禁进入实现');
|
|
91
|
+
}
|
|
92
|
+
if (patch.stage === 'F7' || completed('F6')) {
|
|
93
|
+
if (run.steps.F5.status !== 'completed') throw new Error('实现步骤 F5 尚未完成');
|
|
94
|
+
assertValidation(root, req, run, contents);
|
|
95
|
+
if (patch.stage === 'F7' && run.steps.F6.status !== 'completed') throw new Error('验证步骤 F6 尚未完成');
|
|
96
|
+
}
|
|
97
|
+
if (completed('F7')) assertReview(root, req, run, contents);
|
|
98
|
+
if (patch.stage === 'F8' || completed('F8')) assertDelivery(root, req, run, contents);
|
|
99
|
+
if (completed('F8')) receipt(root, req, run, 'delivery', contents);
|
|
100
|
+
} else {
|
|
101
|
+
if (completed('B4') || patch.stage === 'B5') {
|
|
102
|
+
assertValidation(root, req, run, contents);
|
|
103
|
+
if (patch.stage === 'B5' && run.steps.B4.status !== 'completed') throw new Error('修复与验证步骤 B4 尚未完成');
|
|
104
|
+
}
|
|
105
|
+
if (completed('B5')) { assertDelivery(root, req, run, contents); receipt(root, req, run, 'delivery', contents); }
|
|
106
|
+
}
|
|
107
|
+
const event = run.history.at(-1);
|
|
108
|
+
if (patch.approval) event.approval = run.plan_approval;
|
|
109
|
+
if (patch.validation) event.validation = run.validation;
|
|
110
|
+
if (patch.decision) event.decision = run.decision;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export function reviewInputs(run) {
|
|
114
|
+
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 };
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
export function reviewEvidence(root, req, run, packet, result, contents) {
|
|
119
|
+
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);
|
|
122
|
+
if (result?.run_id !== run.id || result.code !== snapshot.digest || result.inputs !== packet.inputs) throw new Error('审查结果的运行、代码版本或交接内容不匹配,请返回本轮审查结果');
|
|
123
|
+
if (!Array.isArray(result?.findings) || !Array.isArray(result?.coverage?.reviewed) || !Array.isArray(result?.coverage?.uncovered)) throw new Error('审查结果需要 findings 和 coverage.reviewed / uncovered');
|
|
124
|
+
const covered = [...result.coverage.reviewed, ...result.coverage.uncovered];
|
|
125
|
+
const expected = packet.scope.review.map((f) => f.path);
|
|
126
|
+
if (new Set(covered).size !== covered.length || expected.length !== covered.length || expected.some((p) => !covered.includes(p))) throw new Error('审查覆盖范围必须逐文件对应交接材料,未审完的放入 uncovered');
|
|
127
|
+
const ids = new Set();
|
|
128
|
+
for (const f of result.findings) {
|
|
129
|
+
if (!f.id || ids.has(f.id) || !['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].includes(f.severity) || !['confirmed', 'pending'].includes(f.verification)
|
|
130
|
+
|| (f.scope !== undefined && !['in_scope', 'outside'].includes(f.scope))
|
|
131
|
+
|| !f.file || !Number.isInteger(f.line) || f.line < 1 || !f.summary?.trim()) throw new Error('审查问题需要唯一 id、severity、verification、file、正整数 line 与 summary');
|
|
132
|
+
ids.add(f.id);
|
|
133
|
+
}
|
|
134
|
+
const report = receipt(root, req, run, 'review', contents);
|
|
135
|
+
return { snapshot, inputs: packet.inputs, report_hash: report.hash, report_version: report.version, result, at: new Date().toISOString() };
|
|
136
|
+
}
|
package/workflow/lib/runs.mjs
CHANGED
|
@@ -6,6 +6,9 @@ import { find, requirements } from './requirement-read.mjs';
|
|
|
6
6
|
import { parseBranch } from './artifact-model.mjs';
|
|
7
7
|
import { updateMeta } from './meta-store.mjs';
|
|
8
8
|
import { loadWorkspace } from './workspace-read.mjs';
|
|
9
|
+
import { readProfile } from './project.mjs';
|
|
10
|
+
import { isDev, applyDevEvidence, assertReview, assertDelivery, receipt } from './run-gates.mjs';
|
|
11
|
+
import { codeSnapshot } from './code-snapshot.mjs';
|
|
9
12
|
|
|
10
13
|
export const FLOWS = {
|
|
11
14
|
feature: ['Step0', 'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8'],
|
|
@@ -27,19 +30,30 @@ export function allRuns(root, workspace = loadWorkspace(root)) {
|
|
|
27
30
|
|
|
28
31
|
export const branchRuns = (root, branch, workspace) => allRuns(root, workspace).filter((run) => run.branch === branch);
|
|
29
32
|
|
|
30
|
-
export function runState(root, branch, workspace = loadWorkspace(root)) {
|
|
33
|
+
export function runState(root, branch, workspace = loadWorkspace(root), id = null) {
|
|
31
34
|
const runs = branchRuns(root, branch, workspace);
|
|
32
|
-
const current = runs.filter((r) => !terminal(r.status)).at(-1) ?? runs.at(-1) ?? null;
|
|
33
|
-
|
|
35
|
+
const current = id ? runs.find((r) => r.id === id) ?? null : runs.filter((r) => !terminal(r.status)).at(-1) ?? runs.at(-1) ?? null;
|
|
36
|
+
let next = !current ? null : current.pending_finalization ? `先恢复产物收尾:artifact.mjs resume --id ${current.id}` : current.status === 'waiting_user' ? `等待用户:${current.waiting_for}`
|
|
34
37
|
: current.status === 'blocked' ? `处理阻塞:${current.reason}`
|
|
35
38
|
: terminal(current.status) ? `${STATUS_LABELS[current.status]}:${current.kind}(${current.id})`
|
|
36
39
|
: `继续 ${current.stage}(${current.kind},运行 ${current.id})`;
|
|
37
|
-
|
|
40
|
+
let freshness = null;
|
|
41
|
+
if (current && (isDev(current) || current.kind === 'review') && !terminal(current.status) && (current.validation || current.review)) {
|
|
42
|
+
try {
|
|
43
|
+
const snapshot = codeSnapshot(root, current);
|
|
44
|
+
freshness = { validation: current.validation ? snapshot.digest === current.validation.snapshot.digest : null, review: current.review ? current.review.snapshot.digest === snapshot.digest : null };
|
|
45
|
+
if ((freshness.validation === false || freshness.review === false) && !current.pending_finalization) next = isDev(current) ? '代码或基线已变化:回到验证阶段,重新验证、审查并取得交付选择' : '代码或基线已变化:重新审查并生成报告';
|
|
46
|
+
} catch (e) {
|
|
47
|
+
freshness = { validation: false, review: false, reason: e.message };
|
|
48
|
+
if (!current.pending_finalization) next = `核对证据失败:${e.message}`;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
return { branch, current, runs, next, ...(freshness ? { freshness } : {}), ...(workspace.diagnostics.length ? { diagnostics: workspace.diagnostics } : {}) };
|
|
38
52
|
}
|
|
39
53
|
|
|
40
|
-
function applyCheckpoint(run, patch, at, reopen = true) {
|
|
54
|
+
export function applyCheckpoint(run, patch, at, reopen = true) {
|
|
41
55
|
if (!object(patch)) throw new Error('checkpoint 必须是 JSON 对象');
|
|
42
|
-
const allowed = ['stage', 'status', 'size', 'waiting_for', 'reason', 'steps', 'context', 'decision'];
|
|
56
|
+
const allowed = ['stage', 'status', 'size', 'waiting_for', 'reason', 'steps', 'context', 'decision', 'approval', 'implement', 'validation', 'scope'];
|
|
43
57
|
for (const key of Object.keys(patch)) if (!allowed.includes(key)) throw new Error(`不支持修改字段:${key}`);
|
|
44
58
|
if (patch.status !== undefined && !['running', 'waiting_user', 'blocked'].includes(patch.status)) throw new Error('save 的状态只支持 running / waiting_user / blocked;完成用 complete,取消用 cancel');
|
|
45
59
|
if (patch.size !== undefined) {
|
|
@@ -54,6 +68,12 @@ function applyCheckpoint(run, patch, at, reopen = true) {
|
|
|
54
68
|
if (reopen && patch.stage && (stages.indexOf(stage) < stages.indexOf(run.stage) || (status === 'running' && done(run.steps[stage].status)))) {
|
|
55
69
|
for (const name of stages.slice(stages.indexOf(stage))) run.steps[name] = { status: 'pending' };
|
|
56
70
|
run.decision = null;
|
|
71
|
+
if (isDev(run)) {
|
|
72
|
+
const index = stages.indexOf(stage);
|
|
73
|
+
if (run.kind === 'bug' || index <= stages.indexOf('F7')) run.review = null;
|
|
74
|
+
if (run.kind === 'bug' || index <= stages.indexOf('F6')) run.validation = null;
|
|
75
|
+
if (run.kind === 'bug' || index <= stages.indexOf('F4')) run.implementation = null;
|
|
76
|
+
}
|
|
57
77
|
}
|
|
58
78
|
if (patch.steps !== undefined) {
|
|
59
79
|
if (!object(patch.steps)) throw new Error('steps 必须是对象');
|
|
@@ -64,12 +84,18 @@ function applyCheckpoint(run, patch, at, reopen = true) {
|
|
|
64
84
|
run.steps[name] = { ...value, updated_at: at, completed_at: value.status === 'completed' ? (run.steps[name].completed_at ?? at) : null };
|
|
65
85
|
}
|
|
66
86
|
}
|
|
87
|
+
if (patch.scope !== undefined) {
|
|
88
|
+
if (!object(patch.scope) || typeof patch.scope.base !== 'string' || !patch.scope.base.trim() || !Array.isArray(patch.scope.exclude) || patch.scope.exclude.some((v) => typeof v !== 'string')) throw new Error('scope 需要 base 和 exclude 字符串数组');
|
|
89
|
+
if (run.validation && JSON.stringify(run.scope) !== JSON.stringify(patch.scope)) throw new Error('调整审查范围前先回退到实现/验证阶段,使旧证据失效');
|
|
90
|
+
run.scope = patch.scope;
|
|
91
|
+
}
|
|
67
92
|
if (patch.context !== undefined) {
|
|
68
93
|
if (!object(patch.context)) throw new Error('context 必须是对象');
|
|
69
94
|
run.context = { ...run.context, ...patch.context };
|
|
70
95
|
}
|
|
71
96
|
if (patch.decision !== undefined) {
|
|
72
97
|
if (!object(patch.decision) || !['fix', 'deliver'].includes(patch.decision.action) || patch.decision.confirmed !== true) throw new Error('decision 必须记录用户明确确认的 fix / deliver');
|
|
98
|
+
if (patch.decision.accepted_risks !== undefined && (!Array.isArray(patch.decision.accepted_risks) || patch.decision.accepted_risks.some((v) => typeof v !== 'string'))) throw new Error('accepted_risks 必须是已明确接受的问题 id 数组');
|
|
73
99
|
run.decision = { ...patch.decision, at };
|
|
74
100
|
}
|
|
75
101
|
run.stage = stage;
|
|
@@ -94,25 +120,39 @@ export function startRun(root, { branch, kind = 'feature', size = null, input =
|
|
|
94
120
|
const runs = meta.runs ?? {};
|
|
95
121
|
selected = Object.values(runs).find((r) => r.branch === branch && r.kind === kind && !terminal(r.status));
|
|
96
122
|
if (selected) { resumed = true; return meta; }
|
|
123
|
+
const profile = readProfile(root).profile;
|
|
97
124
|
const at = timestamp(); const id = randomUUID();
|
|
98
125
|
selected = applyCheckpoint({ id, kind, size, branch, revision: 1, status: 'running', stage: FLOWS[kind][0],
|
|
99
126
|
created_at: at, updated_at: at, completed_at: null, steps: Object.fromEntries(FLOWS[kind].map((s) => [s, { status: 'pending' }])),
|
|
100
|
-
|
|
127
|
+
scope: { base: meta.base || profile?.main_branch || 'main', exclude: Array.isArray(profile?.review?.exclude) ? profile.review.exclude.filter((v) => typeof v === 'string') : [] },
|
|
128
|
+
artifacts: {}, context: {}, waiting_for: null, reason: null, decision: null, history: [] }, input, at);
|
|
129
|
+
applyDevEvidence(root, req, selected, input, at);
|
|
101
130
|
return { ...meta, runs: { ...runs, [id]: selected }, updated: at };
|
|
102
131
|
}, { root });
|
|
103
132
|
return { ok: true, resumed, dir: req.dir, run: selected };
|
|
104
133
|
}
|
|
105
134
|
|
|
106
|
-
export function
|
|
107
|
-
if (!branch || !id || !['save', 'complete', 'cancel'].includes(action)) throw new Error('需要当前分支、运行 id 和有效动作');
|
|
135
|
+
export function readRun(root, branch, id) {
|
|
108
136
|
const req = requirements(root).find((r) => Object.hasOwn(r.meta.runs ?? {}, id));
|
|
109
137
|
if (!req) throw new Error(`找不到运行:${id}`);
|
|
138
|
+
const run = req.meta.runs[id];
|
|
139
|
+
if (run.branch !== branch) throw new Error('运行属于其他分支,请切换到对应分支后恢复,不要修改原运行的分支');
|
|
140
|
+
return { req, run };
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
export function assertRunVersion(run, branch, revision) {
|
|
144
|
+
if (run.branch !== branch) throw new Error('运行属于其他分支,请切换到对应分支后恢复,不要修改原运行的分支');
|
|
145
|
+
if (!Number.isInteger(revision) || run.revision !== revision) throw new Error(`运行版本冲突,重新读取状态后使用 --expect-revision ${run.revision}`);
|
|
146
|
+
if (terminal(run.status)) throw new Error('运行已结束,不再修改;新的工作请 start 新运行');
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
export function changeRun(root, { branch, id, revision, input = {}, action = 'save' }) {
|
|
150
|
+
if (!branch || !id || !['save', 'complete', 'cancel'].includes(action)) throw new Error('需要当前分支、运行 id 和有效动作');
|
|
151
|
+
const { req } = readRun(root, branch, id);
|
|
110
152
|
let result;
|
|
111
153
|
updateMeta(path.join(req.abs, 'meta.json'), (meta) => {
|
|
112
154
|
const run = structuredClone(meta.runs[id]);
|
|
113
|
-
|
|
114
|
-
if (!Number.isInteger(revision) || run.revision !== revision) throw new Error(`运行版本冲突,重新读取状态后使用 --expect-revision ${run.revision}`);
|
|
115
|
-
if (terminal(run.status)) throw new Error('运行已结束,不再修改;新的工作请 start 新运行');
|
|
155
|
+
assertRunVersion(run, branch, revision);
|
|
116
156
|
const at = timestamp();
|
|
117
157
|
if (action === 'cancel') {
|
|
118
158
|
if (!input.reason?.trim()) throw new Error('取消运行需要 reason');
|
|
@@ -120,13 +160,17 @@ export function changeRun(root, { branch, id, revision, input = {}, action = 'sa
|
|
|
120
160
|
run.history.push({ at, stage: run.stage, status: 'cancelled', reason: input.reason });
|
|
121
161
|
} else {
|
|
122
162
|
applyCheckpoint(run, input, at, action !== 'complete');
|
|
163
|
+
applyDevEvidence(root, req, run, input, at);
|
|
123
164
|
if (action === 'complete') {
|
|
124
165
|
const steps = FLOWS[run.kind];
|
|
125
166
|
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('还有未完成步骤、待用户决定或阻塞,不能标记已完成');
|
|
126
167
|
if (['feature', 'bug'].includes(run.kind)) {
|
|
127
168
|
const required = run.kind === 'feature' ? ['F4', 'F5', 'F6', 'F7', 'F8'] : ['B4', 'B5'];
|
|
169
|
+
assertDelivery(root, req, run);
|
|
170
|
+
receipt(root, req, run, 'delivery');
|
|
128
171
|
if (required.some((s) => run.steps[s].status !== 'completed') || run.decision?.action !== 'deliver' || !run.decision.confirmed) throw new Error('完整 dev 流程必须完成方案、实现、验证、审查和交付,且用户已选择交付');
|
|
129
172
|
}
|
|
173
|
+
if (run.kind === 'review') assertReview(root, req, run);
|
|
130
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'] };
|
|
131
175
|
for (const name of files[run.kind] ?? []) {
|
|
132
176
|
const file = path.join(req.abs, name);
|
|
@@ -103,7 +103,9 @@ export function loadWorkspace(root, { allProjects = false, allBranches = false }
|
|
|
103
103
|
diagnostics.push({ code: 'invalid_run', path: `${req.dir}/meta.json`, message: `运行 ${id} 结构无效,不能恢复` });
|
|
104
104
|
continue;
|
|
105
105
|
}
|
|
106
|
-
|
|
106
|
+
const pending = req.meta.pending_finalization;
|
|
107
|
+
runs.push({ ...run, requirement: req.name, dir: req.dir, project: req.project,
|
|
108
|
+
...(pending?.run_id === id ? { pending_finalization: { kind: pending.kind, id: pending.id } } : {}) });
|
|
107
109
|
}
|
|
108
110
|
}
|
|
109
111
|
artifacts.sort(byArtifactDate);
|
|
@@ -14,6 +14,10 @@ dev / project-review 的 SKILL.md 只保留触发边界、门禁、步骤路由
|
|
|
14
14
|
| requirement-read | 需求目录和元信息读取、查询与分组 |
|
|
15
15
|
| requirements | 需求绑定、产物版本、归档、索引写入 |
|
|
16
16
|
| runs | 运行阶段、用户选择、revision、完成与取消 |
|
|
17
|
+
| run-gates | 方案确认、实现/验证/审查/交付转换门禁,核对证据与版本 |
|
|
18
|
+
| code-snapshot | 基线、HEAD 与工作区文件内容摘要,校验验证/审查仍适用 |
|
|
19
|
+
| artifact-finalize | 草稿检查、正式发布、归档、索引与运行证据登记;在 meta 中记录可恢复收尾 |
|
|
20
|
+
| path-match | 审查范围与代码快照复用的纯 glob 匹配 |
|
|
17
21
|
| meta-store | 元信息写锁与原子替换;写入前自动创建父目录,再按真实路径归一化加锁;读取不创建目录 |
|
|
18
22
|
| document-model | 标题、章节、表格、元信息等纯文本解析 |
|
|
19
23
|
| artifact-model | 产物种类、文件名、分支、日期、发布与沉淀、审查和交付解析 |
|
|
@@ -41,3 +45,9 @@ lib 不依赖 scripts;纯模型不依赖 I/O。读侧不调用 sync 或推进
|
|
|
41
45
|
`lib/capabilities.mjs` 集中探测接入,`resolve.mjs status` 输出本轮能力快照(ready / blockers、通道、模板解析结果),`references/capabilities.md` 定义所有 Skill 共用的失败处理。CodeGraph 的库探测通过其 status 命令交给能力适配器,lib 不导入 Skill 执行脚本。新会话或环境变化时刷新,不持久化个人能力状态到需求元信息。
|
|
42
46
|
|
|
43
47
|
DocNexus 是必装组件:安装器缺失即接入,安装失败不报告完成;已有组件默认复用,`--with-docnexus` 强制更新。模板只从知识库读取,包内模板仅用于导入。知识查询失败不作为空结果继续。CodeGraph、wiki、数据库仍按共享规则选择增强通道;必需目标、需求绑定和语句拦截按各自语义处理。
|
|
48
|
+
|
|
49
|
+
## 执行可靠性
|
|
50
|
+
|
|
51
|
+
关键转换由 run-gates 执行,不仅在 complete 检查。方案批准关联具体正文;验证在执行前 snapshot、执行后登记;review-handoff 从已保存事实和代码范围生成交接材料,不传实现者结论。审查结果同时返回报告草稿与结构化 findings/coverage,主 agent 统一收尾,交付选择绑定该轮代码与报告版本。
|
|
52
|
+
|
|
53
|
+
artifact.mjs 在命令层解析知识模板并传入精确草稿检查;artifact-finalize 不导入命令入口。两次带锁写入先登记 pending_finalization,再发布文档并提交索引与运行;meta 中的待办是恢复依据,不另建状态数据库。中断后拒绝其他元信息写入,resume 重查证据并幂等完成,abort 安全还原原文件。只读命令展示待办,不自动修复。快照与阶段协议见 execution.md。
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
node <skills>/workflow/scripts/resolve.mjs status
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
保留输出作为本轮能力快照;同一项目的流程跳转、子 agent 直接复用,由主 agent
|
|
9
|
+
保留输出作为本轮能力快照;同一项目的流程跳转、子 agent 直接复用,由主 agent 一并交接,可用 workflow-run/tmp/capabilities.json 暂存交接。新会话恢复、切换项目、配置或安装发生变化时重新探测。快照仅本轮使用,不作为团队配置或固定状态写入 meta.json。
|
|
10
10
|
|
|
11
11
|
## 开工门槛
|
|
12
12
|
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# 关键门禁、代码证据与产物收尾
|
|
2
|
+
|
|
3
|
+
完整流程进入方案、实现、验证、审查或交付时读对应小节。快速通道不调用本文的运行与落盘命令。所有命令在业务项目根运行,`<skills>` 为安装目录;JSON 输入文件放 `workflow-run/tmp/`。
|
|
4
|
+
|
|
5
|
+
## 方案与实现门禁
|
|
6
|
+
|
|
7
|
+
首次创建运行仍在 F4 / B4,不提前 bind。`scope` 保存审查基线和明确排除范围,缺省取需求 base/画像 main_branch 与 review.exclude:
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{"scope":{"base":"main","exclude":["unrelated/**"]}}
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
完整流程的文档先写草稿,再统一收尾;不要直接覆盖正式文件后用 sync 代替收尾。模板仍由调用方用 `resolve.mjs template <skill> <id>` 读取:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
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
|
+
```
|
|
18
|
+
|
|
19
|
+
功能方案收尾的 checkpoint 可写 `{"steps":{"F4":{"status":"completed"}}}`;M / L 等用户确认时可同时写 waiting_user 和 waiting_for。bug 的 B4 还包含实现、验证,方案收尾时不能标完成,checkpoint 可省略。已有方案在草稿中保留正文并追加修复方案,更新当前分支和日期。
|
|
20
|
+
|
|
21
|
+
M / L 取得用户实际确认后,用 save 记录 `approval: {"confirmed":true}`,程序绑定当前 plan.md 的 hash/版本;方案变更后旧确认失效。S 完整流程仍须收尾方案,但无需该确认记录。进入实现:
|
|
22
|
+
|
|
23
|
+
- feature:save `{"stage":"F5","status":"running","approval":{"confirmed":true}}`(S 可省 approval)。
|
|
24
|
+
- bug:在 B4 save `{"status":"running","approval":{"confirmed":true},"implement":true}`;之后才改代码。
|
|
25
|
+
|
|
26
|
+
未收尾方案、M / L 未确认、核心步骤 skipped 都会被拒绝。程序校验确认记录与版本,不能替代 agent 核实用户是否真的授权。
|
|
27
|
+
|
|
28
|
+
## 验证证据
|
|
29
|
+
|
|
30
|
+
feature 实现完成后 save F5 completed,进入 F6;bug 在 B4 验证。**测试/操作执行前**生成快照:
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
node <skills>/workflow/scripts/run.mjs snapshot --id <id>
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
保留输出的 `snapshot` 对象,再执行构建、相关/全量测试、lint 与验收操作。执行后 save:
|
|
37
|
+
|
|
38
|
+
```json
|
|
39
|
+
{
|
|
40
|
+
"validation": {
|
|
41
|
+
"snapshot": {"说明":"替换为执行前输出的完整 snapshot 对象,不是此示例"},
|
|
42
|
+
"checks": [
|
|
43
|
+
{"command":"实际执行的测试命令或验收操作","result":"passed"},
|
|
44
|
+
{"command":"无法执行的集成验证","result":"unverified","reason":"缺少测试环境"}
|
|
45
|
+
]
|
|
46
|
+
},
|
|
47
|
+
"steps": {"F6":{"status":"completed"}}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
result 只接受 passed / failed / unverified;失败或未验证须 reason,不能用计划冒充结果。bug 将 F6 改为 B4,保存后进入 B5;feature 保存后进入 F7。若执行期间代码变化,登记失败,重新生成快照并验证。
|
|
52
|
+
|
|
53
|
+
快照包含实际工作分支、基线提交、合并基点、HEAD,以及工作区跟踪/未跟踪文件的内容、删除、执行权限和符号链接;暂存本身不改变内容摘要。子模块/嵌套仓库须固定在干净提交,不能用 dirty 标记代替具体代码证据。除明确排除范围外,也覆盖未改动的项目文件,防止调用方/配置变更使证据过期。忽略 Git 忽略的未跟踪文件,以及 workflow-run、已安装 skills、DocNexus 和 CodeGraph 内部文件,避免写报告使自身失效。不能用 `--branch` 给另一实际 checkout 作证。
|
|
54
|
+
|
|
55
|
+
## 自动审查交接
|
|
56
|
+
|
|
57
|
+
开工 status 输出保留在本轮 `workflow-run/tmp/capabilities.json`,同链路复用,不写需求 meta。进入 F7 / B5 后生成:
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
node <skills>/workflow/scripts/review-handoff.mjs --id <id> --depth 标准 --capabilities workflow-run/tmp/capabilities.json
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
输出 `path` 是交接 JSON,位于 tmp/review/<运行id>/。自动汇总项目/skills 路径、实际基线、排除范围、风险分批、验收和已确认决定、方案、验证命令与结果、上次报告及代码快照。没有能力文件时省略参数,主 agent 补交本轮能力快照;不重新探测。只传事实,不传实现者的自审结论。
|
|
64
|
+
|
|
65
|
+
独立子 agent 按 project-review 第 1~7 步审查,返回报告草稿与结构化结果,主 agent 负责正式收尾并更新同一运行。没有子 agent 时由当前会话同样执行并如实署名。**审查期间不修改被审代码**。JSON 结果结构以 packet.result_schema 为准,run_id / code / inputs 原样回传,以绑定本轮运行、代码版本和交接内容;范围外发现标 scope: outside,不计入本次交付的严重问题门禁。零发现 findings 为空数组,scope.review 中每个文件必须进入 coverage.reviewed 或 uncovered,不能漏报未审文件。
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
node <skills>/workflow/scripts/artifact.mjs finalize --id <id> --expect-revision <revision> --kind review --draft workflow-run/tmp/review.md --packet <交接JSON路径> --result workflow-run/tmp/review-result.json --input workflow-run/tmp/checkpoint.json
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
feature 可在 checkpoint 标 F7 completed;bug 的 B5 此时仍 in_progress。主 agent 取得报告后交给用户,save waiting_user 等待修复或交付。收尾要求交接仍对应当前代码、需求事实、方案和验证;仅进度保存不会让交接失效,改变验收/范围等实质内容须重新审查。
|
|
72
|
+
|
|
73
|
+
独立正式 review 也生成交接材料,R1~R6 记录实际进度,R7 用同一入口收尾 review,再交报告、complete;不要求 dev 的验证或方案。当前协议的代码证据基于实际工作区,正式审查请在目标分支 checkout 中运行;其他分支的只读灵活审查仍可用原 diff 命令,不创建运行。
|
|
74
|
+
|
|
75
|
+
## 交付门禁
|
|
76
|
+
|
|
77
|
+
用户明确选择交付后,feature save F8 running、bug 在 B5 save running,并写 `decision: {"action":"deliver","confirmed":true}`。程序自动绑定本轮报告 hash、版本与代码摘要。存在已复核 CRITICAL / HIGH 时,先说明风险、取得逐项接受,再在 decision.accepted_risks 中列出对应 findings 的 id;普通的“交付”不代表接受未说明风险。
|
|
78
|
+
|
|
79
|
+
只有该选择仍有效,才允许 `artifact.mjs finalize --kind delivery --draft ...`。审查后代码/基线变化或报告被修改,旧选择不能继续用;回 F6(bug 回 B4)、验证、复审、再次取得选择。修复回退会清除旧验证、审查与交付选择;方案改变则还须重新确认。
|
|
80
|
+
|
|
81
|
+
交付摘要和反馈处理后,末步标 completed,再 complete,保存“已完成”与时间。可选提交、发布、知识沉淀仍沿用原授权边界,且在完成标记后处理;若本次运行完成前修改正式正文,需重新收尾,不能只 sync 后用旧收尾凭据 complete。
|
|
82
|
+
|
|
83
|
+
## 统一收尾与中断恢复
|
|
84
|
+
|
|
85
|
+
finalize 先用知识库当前模板 lint 精确的草稿内容,再校验运行 revision、阶段、分支和证据;通过后归档旧版、发布正式文件、更新版本/索引、登记运行证据。checkpoint 只能更新当前产物所属步骤、等待状态和上下文,不能夹带下游阶段或用户确认。输出正式 path、cite、previous、version、lint、run;自检警告和待填写项要告知用户,引用用 cite,归档遵循 requirements.md,不能替用户删除。
|
|
86
|
+
|
|
87
|
+
正式文档先写 tmp 草稿;不要先调用 `requirement.mjs path` 归档再直接覆盖,否则绕过收尾的中断保护。tech / release 分别在 T4 / L4 用 kind tech / release 收尾,使用各自的知识模板;wiki/沉淀后只更新发布或知识元信息仍可显式 sync。
|
|
88
|
+
|
|
89
|
+
两个文件无法一次原子提交,待办保存在同一个 meta.json 的 pending_finalization,草稿副本在 tmp/finalize/。中断期间其他元信息写入会被拒绝,show 的 next 提示恢复:
|
|
90
|
+
|
|
91
|
+
```sh
|
|
92
|
+
node <skills>/workflow/scripts/artifact.mjs resume --id <id>
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
恢复会再次核对代码与正文,已发布的相同文件不重复升版本;原 finalize 命令重试也不会重复推进状态。恢复发现代码变化或正式文件被其他操作改动时,停下保留待办,不覆盖。需要放弃本次收尾时用 `artifact.mjs abort --id <id>`:只在文件仍是本操作原版/新版时恢复原版并清除待办;发生外部冲突则先人工核对。之后回退、重新验证/审查。临时副本保留在 tmp,不删除用户文件。
|
|
@@ -48,17 +48,16 @@ node <skills>/workflow/scripts/requirement.mjs which
|
|
|
48
48
|
|
|
49
49
|
## 落盘
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
node <skills>/workflow/scripts/requirement.mjs path <plan|delivery|review|tech|release>
|
|
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
52
|
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
-
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
- sync
|
|
53
|
+
- 输出 path(相对项目根)、cite(跨文档引用)、previous(上一版归档)、version 和 run。文件名固定,目录只留最新版;文档仓库模式的 cite 为「文档仓库名:仓库内路径」。
|
|
54
|
+
- 旧版归档在 `workflow-run/tmp/old-artifacts/<需求>/<项目>/<种类>_v<N>.md`,不提交;告诉用户归档了什么,不替用户删除。相同命令重试不重复升级版本或状态。
|
|
55
|
+
- 原文第一行的 md-to-wiki 页面记录自动保留,新版仍发布同一页;不能在普通文档收尾中替换页面归属。
|
|
56
|
+
- 文件发布与元信息不能跨文件一次原子提交。待完成收尾保存在同一 meta.json;中断先 `artifact.mjs resume --id <id>`,不能继续 sync / save 越过待办。代码或正文冲突时停止,取消和恢复规则见 execution.md。
|
|
57
|
+
- `requirement.mjs path <种类>` 仍保留为底层旧接口(会预先复制归档),不作为新流程的写入入口。查询已有产物用 artifacts / list,正式写入与 cite 用 finalize 输出。
|
|
58
|
+
- wiki 发布或知识沉淀更新文档元信息后显式 `requirement.mjs sync <path>`。sync 重建索引并保留 runs;需求绑定只由 bind 修改,不根据文档头隐式新增。
|
|
59
|
+
- 文档/索引不一致、元信息损坏或引用缺失进入只读诊断;文件存在不代表运行完成。确认正文后显式 sync,损坏的 meta 先人工核对修复。已有旧运行缺少新证据时回到对应阶段重新收尾/验证,不自动补用户确认。
|
|
60
|
+
- 独立文档仓库在允许提示提交的阶段运行 `requirement.mjs pending`,沿用下节规则;dev 内部审查延后到 F8。
|
|
62
61
|
|
|
63
62
|
## 独立文档仓库
|
|
64
63
|
|
|
@@ -78,12 +77,12 @@ npx @rowansenne/workflow-run docs-repo <团队文档仓库地址> [--project <
|
|
|
78
77
|
|
|
79
78
|
## 文档仓库的提交
|
|
80
79
|
|
|
81
|
-
文档仓库模式下,产物写在另一个 git 仓库里,不会随代码提交。sync
|
|
80
|
+
文档仓库模式下,产物写在另一个 git 仓库里,不会随代码提交。finalize 后运行 pending(或旧 sync 返回 commit 非空)时:
|
|
82
81
|
|
|
83
82
|
**dev F7 审查例外**:审查环节(独立子 agent 或当前会话自查)拿到 `commit` 信息后不询问、不执行文档提交,先交审查报告、等待用户选择修复或交付。选择交付进入 F8 后(完整流程;S 快速通道不落盘,没有待提交产物),再运行 `requirement.mjs pending` 获取当前待提交内容,按下面步骤询问;修复与复审期间继续延后,不改动 `commit_prompt` 配置。
|
|
84
83
|
|
|
85
|
-
1. 把 `commit.files
|
|
86
|
-
2. 用户确认后,按 `commit.commands
|
|
84
|
+
1. 把 pending 的 `files`(旧 sync 为 commit.files)和 `suggested_message` 给用户看,问要不要提交。
|
|
85
|
+
2. 用户确认后,按 pending 的 `commands`(旧 sync 为 commit.commands) 在文档仓库里提交;推送另外问用户,用户同意后再 `git -C workflow-run push`。
|
|
87
86
|
3. 用户不想现在提交就跳过,不再追问;之后随时可以运行 `requirement.mjs pending` 看还有哪些没提交。
|
|
88
87
|
|
|
89
88
|
不想被提示的人可以关掉:`requirement.mjs config --commit-prompt off --local`。这个设置写在 `workflow/profile.local.json`(个人设置,不提交,只影响自己);去掉 `--local` 则写进 `profile.json`,对整个团队生效。关掉后 sync 不再输出 `commit`,产物照常写到文档仓库,由自己决定什么时候提交。
|