@rowansenne/workflow-run 0.35.0 → 0.36.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 (47) hide show
  1. package/CHANGELOG.md +23 -1
  2. package/README.md +2 -0
  3. package/bin/lib/artifact-context.mjs +1 -1
  4. package/bin/lib/docsrepo.mjs +4 -6
  5. package/bin/lib/doctor.mjs +0 -3
  6. package/bin/lib/install.mjs +15 -15
  7. package/create-release-md-doc/SKILL.md.tpl +1 -1
  8. package/create-tech-md-doc/SKILL.md.tpl +1 -1
  9. package/dev/references/delivery.md +3 -3
  10. package/docs/architecture.html +3 -2
  11. package/docs/development.md +10 -4
  12. package/docs/full-install.html +90 -125
  13. package/docs/installation.md +1 -1
  14. package/docs/loan-service-install.html +90 -0
  15. package/docs/team-guide.md +3 -2
  16. package/docs/workflow-control-roadmap.md +144 -0
  17. package/docs/workflow-core-phase-one-report.md +41 -0
  18. package/docs/workflow-core-phase-one.md +317 -0
  19. package/docs/workflows.md +2 -2
  20. package/examples/workflow-core.mjs +26 -0
  21. package/package.json +2 -1
  22. package/project-review/SKILL.md.tpl +1 -1
  23. package/project-review/references/checklist.md.tpl +1 -1
  24. package/project-review/references/reporting.md +2 -2
  25. package/workflow/core/errors.mjs +61 -0
  26. package/workflow/core/index.mjs +286 -0
  27. package/workflow/core/review-handoff.mjs +101 -0
  28. package/workflow/integrations/skill-document-policy.mjs +28 -0
  29. package/workflow/lib/artifact-finalize.mjs +49 -10
  30. package/workflow/lib/code-snapshot.mjs +5 -0
  31. package/workflow/lib/meta-store.mjs +12 -1
  32. package/workflow/lib/project.mjs +165 -14
  33. package/workflow/lib/requirements.mjs +57 -100
  34. package/workflow/lib/review-scope.mjs +262 -0
  35. package/workflow/lib/runs.mjs +11 -1
  36. package/workflow/lib/workspace-read.mjs +13 -4
  37. package/workflow/references/architecture.md +10 -5
  38. package/workflow/references/core-api.md +196 -0
  39. package/workflow/references/execution.md +4 -4
  40. package/workflow/references/profile.md +20 -0
  41. package/workflow/references/requirements.md +12 -12
  42. package/workflow/scripts/artifact.mjs +36 -14
  43. package/workflow/scripts/requirement.mjs +36 -40
  44. package/workflow/scripts/resolve.mjs +2 -2
  45. package/workflow/scripts/review-handoff.mjs +49 -73
  46. package/workflow/scripts/review-scope.mjs +78 -294
  47. package/workflow/scripts/run.mjs +21 -9
package/CHANGELOG.md CHANGED
@@ -4,6 +4,27 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.36.0] - 2026-11-17
8
+
9
+ ### 新增
10
+ - 新增 `workflow/core/index.mjs` 内部程序入口,运行状态、需求绑定、索引维护、产物 finalize 和审查交接可由 Skills 脚本与 Node.js 调用方共用。
11
+ - 新增项目级配置隔离:实例绑定明确 root,不读取核心模块所在项目的 profile;多个规范路径之外的配置副本有歧义时明确报错。
12
+ - 多环境 `--copy` 安装中内容相同的 profile 副本自动视为等价;内容不同时可用 `requirement.mjs config --profile-source` 写入项目级来源,`auto` 恢复自动判断。
13
+ - 审查范围、分类和分批逻辑抽到共享库,审查交接通过核心生成。
14
+
15
+ ### 变更
16
+ - `requirement.mjs which` 改为纯只读;新增 `requirement.mjs reindex`,只刷新派生索引,不提升 versions、不归档、不推进运行或生成证据。
17
+ - `run.mjs` 的操作与导出收口到核心门面;`artifact.mjs finalize` 通过核心和 Skills 文档策略执行。
18
+ - 核心 `artifacts.resume/abort` 冻结为 `{ branch, id, expectedRevision, operationId }`:`expectedRevision` 使用 status 的 `runRevision`,pending 基准 revision 由核心核对;旧操作 ID 不能恢复或中止后来创建的事务。`artifact.mjs` 恢复命令自动读取当前待办身份,CLI 用法保持不变。
19
+ - `requirement.mjs` 不再转导出底层 `bind / which / reindex`,Skills 的状态写操作只能经过 `createWorkflow` 门面。
20
+ - 双入口验收改用安装后的 `run.mjs`、`artifact.mjs`、`review-handoff.mjs` 和真实模板策略推进完整 feature run,覆盖真实 lint 失败、pending 恢复与 finalize 成功重放;发布包测试也验证安装后的脚本与内部核心操作同一运行。
21
+ - trigger 评估不再把 provider 以普通文本返回的 API 错误当成“没有触发 skill”,并会对调用失败或分流不符合预期返回非零退出码;评估会话只开放 `Skill` / `Read`,允许先读普通文件再识别后续 `SKILL.md`,避免把只读探索误判为未触发。
22
+
23
+ ### 移除
24
+ - 删除 `requirement.mjs path`、`nextPath()`、旧 `sync` 命令及版本 bump 直写链。
25
+ - 删除旧需求目录自动迁移入口;用户工作区中的历史目录和 `old-artifacts/` 不会被自动删除或移动。
26
+ - 旧流程已确认无使用者;包含第一阶段的下一版本 `0.36.0` 按 pre-1.0 规则显式发布破坏性命令变化,不提供兼容壳或迁移。
27
+
7
28
  ## [0.35.0] - 2026-11-16
8
29
 
9
30
  ### 新增
@@ -463,7 +484,8 @@
463
484
  - 安装器改为单一 Node 实现,`init-skills.sh` / `init-skills.ps1` 只是薄封装。
464
485
  - `code-review` 改名为 `project-review`,升级时自动清理旧名。
465
486
 
466
- [Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.26.0...HEAD
487
+ [Unreleased]: https://github.com/guilianerde/skills-init/compare/v0.36.0...HEAD
488
+ [0.36.0]: https://github.com/guilianerde/skills-init/compare/v0.35.0...v0.36.0
467
489
  [0.26.0]: https://github.com/guilianerde/skills-init/compare/v0.25.0...v0.26.0
468
490
  [0.21.0]: https://github.com/guilianerde/skills-init/compare/v0.20.0...v0.21.0
469
491
  [0.20.0]: https://github.com/guilianerde/skills-init/compare/v0.19.0...v0.20.0
package/README.md CHANGED
@@ -56,3 +56,5 @@ npx @rowansenne/workflow-run@latest seed-templates --update # 补入模板并更
56
56
  [安装与升级](docs/installation.md) · [工作流与命令](docs/workflows.md) · [外部能力集成](docs/integrations.md) · [团队指南](docs/team-guide.md) · [维护与发布](docs/development.md) · [更新记录](CHANGELOG.md)
57
57
 
58
58
  [架构图解](docs/architecture.html) · [分步安装教程](docs/full-install.html)
59
+
60
+ 架构演进:[整体开发目标](docs/workflow-control-roadmap.md) · [第一阶段方案](docs/workflow-core-phase-one.md) · [第一阶段实施报告](docs/workflow-core-phase-one-report.md)
@@ -13,7 +13,7 @@ const BLOCK = [
13
13
  '- dev 工作流仅在用户实际调用 `/dev` / `$dev`、点选 dev skill,或明确要求使用 dev / 完整开发工作流时启动。普通分析、问答、代码修改、修 bug、重构、测试、提交代码和推送都不构成启动授权;讨论 dev 或引用命令示例也不构成授权。',
14
14
  '- 未获 dev 流程授权时,直接处理当前任务,不自动做工作流开工探测、确认需求名、绑定需求、创建运行或补齐需求 / 方案 / 审查 / 交付文档,也不主动询问是否开启 dev。已授权的同一 dev 任务可按当前阶段续接;只问分析或要求提交代码时仅处理当前请求,不重启或自行推进流程。旧运行、旧产物和分支绑定不构成新任务或新会话的恢复授权。',
15
15
  `- 普通聊天中生成的报告、分析、方案、草稿、导出等辅助文件,默认写到项目根的 \`${HOME}/other/\`(需要时创建,可按主题建子目录)。不要因为分支已绑定需求就放进需求目录。`,
16
- `- \`${HOME}/docs/requirements/\` 只存通过 dev、project-review、create-tech-md-doc、create-release-md-doc 等工作流生成的正式需求产物。普通聊天不得为辅助文件调用 requirement.mjs bind / path / sync 或 run.mjs,不创建或更新需求 meta.json,也不将这些文件计入需求产物和运行状态。`,
16
+ `- \`${HOME}/docs/requirements/\` 只存通过 dev、project-review、create-tech-md-doc、create-release-md-doc 等工作流生成的正式需求产物。普通聊天不得为辅助文件调用 requirement.mjs bind / reindex、run.mjs 或 artifact.mjs,不创建或更新需求 meta.json,也不将这些文件计入需求产物和运行状态。`,
17
17
  '- 项目源码、测试、配置及已有文件的维护仍遵循项目原目录;工作流自身指定的临时目录、知识库等路径沿用各自规则。用户明确指定输出路径时按用户要求执行,不自动搬移已有文件。',
18
18
  END,
19
19
  ].join('\n');
@@ -2,7 +2,6 @@
2
2
  // - workflow-run/ 里没有内容(或只有 tmp/):直接克隆
3
3
  // - 已有产物、DocNexus 等内容:原地 git init 并接上远端。远端是空仓库时本地内容就是文档仓库的第一批内容;
4
4
  // 远端已有内容时检出远端,本地文件和远端同路径冲突就退回原状、列出冲突的文件(不合并)
5
- // - 先把旧结构的产物迁到 <需求>/<项目名>/
6
5
  // - 代码仓库 .gitignore 加 /workflow-run/;文档仓库的 .git/info/exclude 加 /tmp/(本机临时文件不进文档仓库)
7
6
  // - 项目名写进 workflow/profile.json 的 artifacts.project(--project,或沿用已有的,默认 git 远端仓库名)
8
7
  // - 文档仓库里有 DocNexus 时接上本项目的链接与段落;还没装依赖时提示
@@ -12,9 +11,9 @@ import fs from 'node:fs';
12
11
  import path from 'node:path';
13
12
  import { spawnSync } from 'node:child_process';
14
13
  import { HOME, step, ok, warn, toPosix, findManifests, docnexusBin } from './core.mjs';
15
- import { updateGitignore, excludeHomeTmp, reportMigration } from './install.mjs';
14
+ import { updateGitignore, excludeHomeTmp } from './install.mjs';
16
15
  import { refreshDocNexusLinks } from './docnexus.mjs';
17
- import { layout, setConfig, artifactsConfig, suggestProject, migrateLayout } from '../../workflow/scripts/requirement.mjs';
16
+ import { layout, setConfig, artifactsConfig, suggestProject } from '../../workflow/scripts/requirement.mjs';
18
17
 
19
18
  const git = (cwd, args, opts = {}) => spawnSync('git', args, { cwd, encoding: 'utf8', ...opts });
20
19
 
@@ -31,11 +30,10 @@ function show(root) {
31
30
  return 0;
32
31
  }
33
32
 
34
- // workflow-run/ 里已有内容:原地变成文档仓库。返回是否成功;失败时 workflow-run/ 保持原样(只多了迁移到新结构的产物)
33
+ // workflow-run/ 里已有内容:原地变成文档仓库。返回是否成功。
35
34
  function inPlace(root, home, url, project, installed) {
36
- // 先定项目名,再把旧结构迁到 <需求>/<项目名>/,这样和文档仓库里其他服务的目录对得上
35
+ // 先定项目名,未配置时后续初始化以该名字写入 target profile。
37
36
  if (project && installed) setConfig(root, { project });
38
- reportMigration(migrateLayout(root));
39
37
  const remote = git(root, ['ls-remote', '--symref', url]);
40
38
  if (remote.status !== 0) { warn(`连不上 ${url}(地址、权限或网络),没有改动`); return false; }
41
39
  const heads = remote.stdout.split('\n').filter((l) => /\trefs\/heads\//.test(l)).map((l) => l.split('\t')[1].replace('refs/heads/', ''));
@@ -6,7 +6,6 @@ import { spawnSync } from 'node:child_process';
6
6
  import { PKG, CANON_DIR, INSTALL_BASES, LINK_ENVS, HOME, SKILLS, step, ok, warn, fail, toPosix, fileHash, readManifest, lstat, findManifests, cmpVersion } from './core.mjs';
7
7
  import { reportTemplateStatus, legacyDocNexusPaths } from './docnexus.mjs';
8
8
  import { codegraphVersion } from './codegraph.mjs';
9
- import { legacyRequirements } from '../../workflow/scripts/requirement.mjs';
10
9
 
11
10
  // upgrade = 用清单里记录的环境与模式非交互重装;数据库配置原样保留
12
11
  export function upgradeOptions(o) {
@@ -111,8 +110,6 @@ export function doctor(root, offline) {
111
110
  const mode = st.artifacts?.mode === 'repo' ? `独立文档仓库(${HOME}/ 自己是 git 仓库)` : '随项目提交';
112
111
  if (st.artifacts && !st.artifacts.ok) meh(`产出目录 ${HOME}/:${mode},${st.artifacts.how}`);
113
112
  else ok(`产出目录 ${HOME}/:${mode}${st.artifacts?.project ? `,本项目的产物在 docs/requirements/<需求>/${st.artifacts.project}/` : ''}`);
114
- const legacy = legacyRequirements(root);
115
- if (legacy.length) meh(`${legacy.length} 个需求还是旧结构(文件直接放在 docs/requirements/<需求>/ 下):运行 npx @rowansenne/workflow-run upgrade 迁到 <需求>/<项目名>/`);
116
113
  if (st.docnexus.ok) {
117
114
  if (!reportTemplateStatus(root, meh)) ok('DocNexus 已接入,文档模板齐全且与默认模板同步(或为团队定制版)');
118
115
  } else if (fs.existsSync(path.join(root, '.docnexus', 'project.json'))) bad('DocNexus 配置或运行环境不完整:需要 format 7、output_dir=workflow-run 和 .docnexus/ 下的 CLI,运行 upgrade --with-docnexus 修复');
@@ -5,7 +5,7 @@ import path from 'node:path';
5
5
  import { TPL_DIR, PKG, CANON_DIR, INSTALL_BASES, SKILLS, SKILL_LIST, USER_FILES, MANIFEST, ok, warn, fail, readJson, walk, toPosix, sameFile, writeFile, render, sha256, fileHash, readManifest, removeEmptyDirs, lstat, timestamp, removeLink, HOME } from './core.mjs';
6
6
  import { writeDbConfig } from './db.mjs';
7
7
  import { linkPointsTo } from './uninstall.mjs';
8
- import { layout, ensureIgnore, homeIsRepo, migrateLayout, IGNORE_LINE, TMP_DIR } from '../../workflow/scripts/requirement.mjs';
8
+ import { layout, ensureIgnore, homeIsRepo, IGNORE_LINE, TMP_DIR } from '../../workflow/scripts/requirement.mjs';
9
9
  import { detectEnv } from '../../workflow/lib/project.mjs';
10
10
  import { rotate as rotateFeedback, ensureUnionMerge } from '../../workflow/scripts/feedback.mjs';
11
11
 
@@ -268,23 +268,23 @@ export function excludeHomeTmp(root) {
268
268
  export function setupHome(root) {
269
269
  if (ensureIgnore(root)) ok(`.ignore 已加上 ${IGNORE_LINE}(需求产物不参与代码搜索)`);
270
270
  excludeHomeTmp(root);
271
- const L = layout(root);
272
- if (L.mode === 'repo' && !L.ok) warn(`${HOME}/ 是独立的文档仓库,还没配置本项目的项目名:${L.hint}`);
273
- reportMigration(migrateLayout(root));
271
+ try {
272
+ const L = layout(root);
273
+ if (L.mode === 'repo' && !L.ok) warn(`${HOME}/ 是独立的文档仓库,还没配置本项目的项目名:${L.hint}`);
274
+ } catch (error) {
275
+ if (error.code !== 'PROJECT_CONFIG_AMBIGUOUS') throw error;
276
+ warn(`${error.message};安装已完成,但依赖项目配置的核心操作会暂停,先运行 requirement.mjs config --profile-source <环境|路径> 明确来源`);
277
+ }
274
278
  // 运行反馈只收当前版本的:装了新版本就清掉本项目旧版本的记录(随 workflow-run/ 提交过的,git 历史里仍可找回)
275
- const removed = rotateFeedback(root, PKG.version);
279
+ let removed = 0;
280
+ try {
281
+ removed = rotateFeedback(root, PKG.version);
282
+ } catch (error) {
283
+ if (error.code !== 'PROJECT_CONFIG_AMBIGUOUS') throw error;
284
+ warn('运行反馈轮换已跳过:先运行 requirement.mjs config --profile-source <环境|路径> 明确 profile 来源');
285
+ }
276
286
  const attr = ensureUnionMerge(root);
277
287
  if (attr?.action === 'added') ok(`${attr.file} 已加上 ${attr.rule}(文档仓库里运行反馈多分支合并时保留两边的记录)`);
278
288
  if (attr?.action === 'removed') ok(`${attr.file} 已去掉 ${attr.rule}(随代码提交时不再改代码仓库的 .gitattributes);改动需要你提交`);
279
289
  if (removed) ok(`运行反馈:已清空旧版本的 ${removed} 条记录(${HOME}/feedback/),从这一版重新收集;改动需要你提交`);
280
290
  }
281
-
282
- // 旧结构(<需求>/ 下直接放文件)迁到 <需求>/<项目名>/ 的结果
283
- export function reportMigration(r) {
284
- if (r.moved.length) {
285
- const reqs = [...new Set(r.moved.map((m) => path.posix.dirname(m.from)))];
286
- ok(`需求产物已迁到新结构 <需求>/${r.project}/(${reqs.length} 个需求、${r.moved.length} 个文件,被 git 跟踪的用 git mv):${reqs.join('、')}`);
287
- ok(`项目名 ${r.project} 记在 workflow/profile.json;迁移的改动(含 profile.json)需要你提交`);
288
- }
289
- for (const s of r.skipped) warn(`${s.dir} 没有迁移:${s.reason}。处理后重跑 npx @rowansenne/workflow-run upgrade`);
290
- }
@@ -75,7 +75,7 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
75
75
  ### Step 4 — 写文件
76
76
 
77
77
  - 正式收尾:Step 4 进入 L4,先写 `workflow-run/tmp/release-doc.md` 草稿,再用 `node <skills>/workflow/scripts/artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind release --draft <草稿> --branch <dev分支>` 自检、归档旧版、发布并更新索引/运行证据;使用返回的 path / cite,规则见 `<skills>/workflow/references/execution.md`。
78
- - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
78
+ - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息只刷新派生索引时显式运行 `requirement.mjs reindex`。
79
79
  - 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-release-md-doc --facts` 自检(`--facts` 按元信息行的对比分支核对正文里的类名、文件、接口、表名):有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符、缺元信息行);「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
80
80
  - 再把路径和摘要告诉用户,按取材规则列出实际引用的 dev 产物及版本。
81
81
 
@@ -78,7 +78,7 @@ PRD 参考:<pageId 或 URL 或「无」/「PRD 增强已跳过」>
78
78
  ### Step 4 — 写文件
79
79
 
80
80
  - 正式收尾:Step 4 进入 T4,先写 `workflow-run/tmp/tech-doc.md` 草稿,再用 `node <skills>/workflow/scripts/artifact.mjs finalize --id <运行id> --expect-revision <revision> --kind tech --draft <草稿> --branch <dev分支>` 自检、归档旧版、发布并更新索引/运行证据;使用返回的 path / cite,规则见 `<skills>/workflow/references/execution.md`。
81
- - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息仍可显式 sync。
81
+ - 收尾输出 previous 非空时告诉用户上一版的归档位置,不能替用户删除;中断先 `artifact.mjs resume --id <运行id>`。独立文档仓库的提交提示用 `requirement.mjs pending`,按 requirements.md 处理;后续 wiki/沉淀元信息只刷新派生索引时显式运行 `requirement.mjs reindex`。
82
82
  - 收尾前对草稿运行 `node <skills>/workflow/scripts/lint-doc.mjs <草稿> --skill create-tech-md-doc --facts --diff <main>...<dev>` 自检,显式按三点范围核对正文里的类名、文件、接口、表名。有「错误」先修正再交付(缺必填章节、残留 `{{...}}` 占位符);不再强制可见元信息行,但隐藏分支仍须与运行一致。「警告」按实际情况处理,其中「在 diff 和代码里都找不到」的名字逐个核实:确属编造就改成 diff 里的真实名字或写「待补充」,是外部系统 / 配置中心的名字就保留;「提示」里的待填写位置在交付摘要中告诉用户。
83
83
  - 再把路径和摘要告诉用户,按取材规则列出实际引用的 dev 产物及版本。
84
84
 
@@ -25,7 +25,7 @@
25
25
  完整流程:
26
26
 
27
27
  1. **落盘交付说明**:模板路径用 `node <skills>/workflow/scripts/resolve.mjs template dev delivery-template.md` 取,先写到 tmp 草稿,按 execution.md 用 `artifact.mjs finalize --kind delivery` 发布(见 Artifact Location)。元信息行的「对比分支」写当前分支和 `profile.main_branch`,`artifacts.mjs`、project-review、上线方案靠它找到这份交付;「参考产物」写 requirement.md 的 cite / 版本、最新方案与审查报告。「审查」节记录报告结论、修复与复审结果、用户选择交付及接受的遗留风险。尚未发起沉淀询问时,元信息先写「未询问」,再按第 5 步更新。小改动每节一两行即可,不适用的节写「无」,但验证结果必须如实。
28
- 2. **自检与收尾**:finalize 内部使用知识库交付模板检查草稿,有错误先修正;成功输出正式路径、cite 和版本。不要直接覆盖正式文件后用 sync 代替。
28
+ 2. **自检与收尾**:finalize 内部使用知识库交付模板检查草稿,有错误先修正;成功输出正式路径、cite 和版本。不要直接覆盖正式文件后用 reindex 代替。
29
29
  3. **对话里给摘要**:结果、验证(含未验证项)、最新审查报告路径与结论、遗留问题和用户接受的风险、配置 / SQL 有无、交付文件路径;不必把全文贴进对话。
30
30
  4. **记录运行反馈**(不问用户):按 `<skills>/workflow/references/feedback.md` 运行 `node <skills>/workflow/scripts/feedback.mjs add --skill dev --model <模型名> --mode <feature|bug> --size <S|M|L> --fast <yes|no> --rounds <提问轮数> --corrections <用户纠正理解的次数> --acceptance <已验证>/<总数> --baseline-failures <n>`,有跳过的步骤、不清楚或做不到的规则、用户的抱怨时再加 `--skipped` / `--unclear` / `--feedback`。只写过程,不写代码和业务名词;报错就提一句,不影响交付。
31
31
  完成上述交付摘要与反馈后,按运行状态协议将 F8(bug 为 B5)标 completed 并 complete。下面的可选后续动作在完成标记后处理。
@@ -39,7 +39,7 @@
39
39
  - 有 → 明确问用户「要不要启动 DocNexus 流程,把本次交付沉淀到 DocNexus?」,并列出建议沉淀的条目;发起询问时将交付说明的元信息改成「未沉淀」,成功入库后再写知识路径,避免将已询问但尚未入库算成「未询问」。
40
40
  - 用户同意 → 以交付说明为来源,按 DocNexus 入口 skill `docnexus` 的 capture 流程写入;正文只写知识,不写分支、路径;有 facts 时按 `<skills>/workflow/references/docnexus.md`「沉淀的来源」的格式写 provenance;分类用 `node <skills>/workflow/scripts/resolve.mjs category dev` 的结果作为调用方显式分类封存(见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」)。只沉淀确认过的事实,不沉淀「未验证」「待确认」的内容;知识库已有同主题的沉淀时更新那一篇(带 `--base-version`),不重复新建。写入成功后把交付说明的「DocNexus」元信息行改成 `workflow-run/docnexus/library/<path>`,并回报给用户。
41
41
  - 用户不同意 → 交付说明的元信息行改成「未沉淀」,不再追问。
42
- - 元信息更新后运行 `requirement.mjs sync <交付路径>`;F7 内部审查报告的「未询问」不随此结论改变。
42
+ - 元信息更新后运行 `requirement.mjs reindex`;它不修复正文 hash 或旧交付证据。F7 内部审查报告的「未询问」不随此结论改变。
43
43
 
44
44
  ## Artifact Location
45
45
 
@@ -47,4 +47,4 @@
47
47
 
48
48
  - **需求名**:Step 0 已运行 `requirement.mjs which` 并问定名字。第一次落盘前运行 `requirement.mjs bind --name "<需求名>"`(用户明确同意按分支名生成时不带 `--name`);S 快速通道不 bind、不落盘。缺陷修复同样处理(可以选择挂到原需求下)。
49
49
  - **正式写入**:按 `<skills>/workflow/references/execution.md`,澄清清单、需求、方案、审查、交付都先写 tmp 草稿,再用 `artifact.mjs finalize --kind clarification|requirement|plan|review|delivery` 完成自检、旧版归档、索引与运行证据登记。缺陷修复在 B4 的方案草稿中保留原文并追加修复方案,不另建正式文件。
50
- - 使用输出的 path / cite 引用;previous 非空时告知上一版归档位置,不能替用户删除。中断先 `artifact.mjs resume --id <id>`,不能继续 sync / save 覆盖待办。独立文档仓库在交付完成后运行 pending,按 requirements.md 提示提交。已完成交付的 wiki/DocNexus 元信息更新仍显式 sync。
50
+ - 使用输出的 path / cite 引用;previous 非空时告知上一版归档位置,不能替用户删除。中断先 `artifact.mjs resume --id <id>`,不能继续 reindex / save 覆盖待办。独立文档仓库在交付完成后运行 pending,按 requirements.md 提示提交。已完成交付的 wiki/DocNexus 元信息更新使用显式 reindex。
@@ -275,7 +275,7 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
275
275
  <div class="tag">命令脚本<small>workflow/scripts · 确定性命令</small></div>
276
276
  <div class="cells">
277
277
  <div class="cell"><b>resolve.mjs</b><span>模板来源、能力状态</span></div>
278
- <div class="cell"><b>requirement.mjs</b><span>需求绑定、产物路径</span></div>
278
+ <div class="cell"><b>requirement.mjs</b><span>需求绑定与派生索引维护</span></div>
279
279
  <div class="cell"><b>run.mjs</b><span>运行状态与恢复</span></div>
280
280
  <div class="cell"><b>artifact.mjs</b><span>产物收尾、中断恢复与安全取消</span></div>
281
281
  <div class="cell"><b>review-handoff.mjs</b><span>审查交接与结构化结果</span></div>
@@ -296,12 +296,13 @@ footer { margin-top: 40px; font-size: 13px; color: var(--muted); }
296
296
  <div class="cell"><b>artifact-model</b><span>产物类型与元信息解析(纯模型,无 I/O)</span></div>
297
297
  <div class="cell"><b>requirement-read</b><span>需求目录与元信息读取</span></div>
298
298
  <div class="cell"><b>workspace-read</b><span>工作区/Git 统一快照,一次命令读一遍</span></div>
299
- <div class="cell"><b>requirements</b><span>绑定、版本、归档、sync</span></div>
299
+ <div class="cell"><b>requirements</b><span>绑定与派生索引;正式发布由 finalize 负责</span></div>
300
300
  <div class="cell"><b>runs</b><span>运行阶段、revision、完成校验</span></div>
301
301
  <div class="cell"><b>run-gates</b><span>方案、验证、审查与交付门禁</span></div>
302
302
  <div class="cell"><b>code-snapshot</b><span>代码内容摘要与证据有效性</span></div>
303
303
  <div class="cell"><b>artifact-finalize</b><span>发布、归档、索引与可恢复收尾</span></div>
304
304
  <div class="cell"><b>path-match</b><span>审查与代码证据共用的范围匹配</span></div>
305
+ <div class="cell"><b>review-scope</b><span>审查范围、跳过规则、风险分类与分批</span></div>
305
306
  <div class="cell"><b>meta-store</b><span>写锁与原子替换</span></div>
306
307
  </div>
307
308
  </div>
@@ -64,15 +64,21 @@ workflow-run(安装器仓库)/
64
64
  ├── docs/ # 专题文档与图文教程
65
65
  ├── workflow/
66
66
  │ ├── SKILL.md.tpl · skill.json
67
+ │ ├── core/ # 内部程序入口;实现统一由 Skills 脚本和 Node.js 调用方使用
68
+ │ │ ├── index.mjs # createWorkflow、操作表、错误契约
69
+ │ │ ├── errors.mjs # 稳定错误 code 与领域错误映射
70
+ │ │ └── review-handoff.mjs # 代码 / 文档审查交接组装
71
+ │ ├── integrations/ # Skills 模板策略等外围装配,不进入核心依赖
67
72
  │ ├── lib/ # 共享核心;不反向依赖 scripts 命令入口
68
73
  │ │ ├── project.mjs # 布局、画像、环境与配置
69
74
  │ │ ├── requirement-read.mjs # 需求目录与元信息读取
70
- │ │ ├── requirements.mjs # 绑定、版本归档与索引同步
75
+ │ │ ├── requirements.mjs # 需求绑定、派生索引维护
71
76
  │ │ ├── runs.mjs # 运行状态、阶段与完成校验
72
77
  │ │ ├── run-gates.mjs # 方案、验证、审查与交付门禁
73
78
  │ │ ├── code-snapshot.mjs # 代码内容摘要,绑定验证和审查证据
74
79
  │ │ ├── artifact-finalize.mjs # 可恢复的产物收尾
75
80
  │ │ ├── path-match.mjs # 共享范围匹配
81
+ │ │ ├── review-scope.mjs # 审查范围、跳过规则、风险分类与分批
76
82
  │ │ ├── meta-store.mjs # 写锁与原子存储
77
83
  │ │ ├── document-model.mjs # 标题、章节、表格等纯文本模型
78
84
  │ │ ├── artifact-model.mjs # 产物类型、元信息、审查与交付解析
@@ -87,8 +93,8 @@ workflow-run(安装器仓库)/
87
93
  │ ├── scripts/template.mjs # 修改 / 创建模板:草稿 → 校验与影响 → 保存
88
94
  │ ├── scripts/tables.mjs # 找出改动涉及的数据库表
89
95
  │ ├── scripts/artifact.mjs # 草稿收尾 / 中断恢复 / 安全取消
90
- │ ├── scripts/review-handoff.mjs # 自动生成审查交接与结果结构
91
- │ ├── scripts/requirement.mjs # 产物按需求归档:绑定需求名、落盘路径、meta.json
96
+ │ ├── scripts/review-handoff.mjs # 参数 / 文件 I/O;调用 core reviews.prepare
97
+ │ ├── scripts/requirement.mjs # 参数 / 输出;调用 core 的 bind / which / reindex
92
98
  │ ├── scripts/view.mjs # 项目文档视图(本地静态页面)
93
99
  │ ├── scripts/make-template.mjs # 从样例文档抽模板骨架
94
100
  │ ├── scripts/doc-sections.mjs # 原解析导出入口,转交 lib/document-model.mjs
@@ -175,7 +181,7 @@ workflow-run(安装器仓库)/
175
181
 
176
182
  dev 与 project-review 的 SKILL.md 保留门禁、步骤路由、必要命令和结果去向;进入阶段前才读取对应 reference 的小节。dev 的开工、调研方案、实现验证、审查交付和缺陷修复分开加载;审查的方法、复核、报告与后续也分开加载。完整流程的步骤编号、用户选择、运行状态与正式产物规则沿用原协议,必守规则不藏在脚本注释中。
177
183
 
178
- 状态查询、文档视图、效果报告和 PR 描述共用 `workflow/lib/workspace-read.mjs` 的单次命令内存快照,正文与元信息采集一次,使用统一解析规则。需求绑定、运行状态和已登记版本来自 `meta.json`;正文、文档头和发布记录来自 Markdown,产物索引由显式 `sync` 重建。`list` 只读,`sync` 不再从文档头隐式增加绑定分支,绑定使用 `bind`。跨项目视图仍展示全部服务,分支查询和效果报告默认当前项目;`--all-branches` 保持同路径工作区优先,Git 中的版本信息从同一引用读取。异常数据通过 diagnostics 报告,可读的正文仍展示,读取不修复或覆盖元信息。边界与数据归属详见 [内部架构](../workflow/references/architecture.md)。
184
+ 状态查询、文档视图、效果报告和 PR 描述共用 `workflow/lib/workspace-read.mjs` 的单次命令内存快照,正文与元信息采集一次,使用统一解析规则。需求绑定、运行状态和已登记版本来自 `meta.json`;正文、文档头和发布记录来自 Markdown,派生产物索引由显式 `reindex` 重建。`list` 与 `which` 只读,`reindex` 不修改 versions、runs、revision、批准、证据或正文,绑定使用 `bind`。跨项目视图仍展示全部服务,分支查询和效果报告默认当前项目;`--all-branches` 保持同路径工作区优先,Git 中的版本信息从同一引用读取。异常数据通过 diagnostics 报告,可读的正文仍展示,读取不修复或覆盖元信息。边界与数据归属详见 [内部架构](../workflow/references/architecture.md),程序接口见 [core-api.md](../workflow/references/core-api.md)。
179
185
 
180
186
  新增一个 skill 就是新建目录、写 `SKILL.md.tpl` 和 `skill.json`,再加进 `package.json` 的 `files`。`tests/test-skills-meta.mjs` 会检查它们是否一致。
181
187