@rowansenne/workflow-run 0.25.0 → 0.27.0

package/bin/workflow-run.mjs

@@ -23,6 +23,7 @@ import { findExistingDbConfig, getDb } from './lib/db.mjs';
 import { report, installSkills, linkSkills, updateGitignore, setupHome, recordEnv } from './lib/install.mjs';
 import { setupCodeGraph } from './lib/codegraph.mjs';
 import { uninstall } from './lib/uninstall.mjs';
+import { writeArtifactContext } from './lib/artifact-context.mjs';
 import { checkNodeForDocNexus, setupDocNexus, refreshDocNexusLinks, cleanupLegacyDocNexus, templateRecords, saveTemplateRecords, reportTemplateStatus, installedSkills, docnexusConnected, printTemplateDiffs } from './lib/docnexus.mjs';
 import { upgradeOptions, doctor } from './lib/doctor.mjs';
 import { docsRepo } from './lib/docsrepo.mjs';
@@ -35,7 +36,7 @@ const HELP = `用法: workflow-run [命令] [选项]
 命令：
   init（默认）         安装或重装 skills
   upgrade              按安装清单里的环境与模式非交互升级到当前版本（保留数据库配置等用户配置；skills 文件一律更新为新版，手改过的先备份到 workflow-run/tmp/upgrade-backup/）；
-                       已接入 DocNexus 时顺带导入新增的文档模板（只新增，不覆盖已有模板）
+                       加 --with-docnexus 时把 DocNexus 包也升到最新版（@latest），刷新 skill 链接与 CLAUDE.md / AGENTS.md 段落，并导入新增的文档模板（只新增，不覆盖已有模板）；不加则复用已安装的 DocNexus；缺失时自动安装，并导入新增模板
   doctor               自检：版本、手改 / 缺失文件、软链接、项目画像、DocNexus 模板、数据库连通性、.gitignore
   uninstall            按安装清单卸载本项目装的 skills 与链接（用户配置备份到 workflow-run/tmp/uninstall-backup/）
   seed-templates       只把自带的文档模板导入 DocNexus（workflow-run/docnexus/library/templates/，已有的不覆盖）
@@ -49,11 +50,11 @@ init 选项：
   --envs <列表>        环境，逗号分隔：codex,claude,doubao,qwen,workbuddy；all = 全部（不传则交互选择）
   --skip-db            跳过数据库连接配置
   --yes                非交互：使用已有数据库配置；都没有且未 --skip-db 时报错退出
-  --with-docnexus      同时接入 DocNexus 文档库（装在 workflow-run/docnexus/，需 Node >= 22.13 与 npm），并导入文档模板
+  --with-docnexus      强制更新必装的 DocNexus 到最新版（默认缺失即安装、已安装则复用；运行环境在 .docnexus/，需 Node >= 22.13 与 npm）
   --with-codegraph     同时接入 CodeGraph 代码图谱：没有 codegraph 命令时 npm 全局安装，为 claude / codex 写项目级 MCP 配置，并建本项目索引（.codegraph/）
   --copy               不用软链接，各环境独立拷贝
   --skills <列表>      只装这些 skill（逗号分隔），自动带上 skill.json 里 requires 声明的依赖；缺省为全部
-  --seed-templates     安装后把文档模板导入 DocNexus；接入 DocNexus 后文档类 skill 只从知识库取模板
+  --seed-templates     安装已自动补入文档模板，此参数可省略
   --uninstall          同 uninstall 命令
 seed-templates 选项：
   --update             同时把「导入后未改动、但默认模板有新版」的知识库模板更新为新版
@@ -75,7 +76,7 @@ view 选项：
   -h, --help           显示帮助`;
 
 function parseArgs(argv) {
-  const o = { cmd: 'init', envs: '', skipDb: false, yes: false, withDocNexus: false, withCodeGraph: false, copy: false, seedTemplates: false, update: false, diff: false, skills: '', offline: false, root: process.cwd() };
+  const o = { cmd: 'init', envs: '', skipDb: false, yes: false, withDocNexus: false, withCodeGraph: false, copy: false, update: false, diff: false, skills: '', offline: false, root: process.cwd() };
   let cmdGiven = false; // 命令可以出现在选项之间（封装脚本会先传 --project-root）
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -88,7 +89,7 @@ function parseArgs(argv) {
       case '--with-codegraph': o.withCodeGraph = true; break;
       case '--copy': o.copy = true; break;
       case '--skills': o.skills = val(); break;
-      case '--seed-templates': o.seedTemplates = true; break;
+      case '--seed-templates': break; // 安装始终补入模板，保留旧参数写法
       case '--uninstall': o.cmd = 'uninstall'; cmdGiven = true; break;
       case '--offline': o.offline = true; break;
       case '--update': o.update = true; break;
@@ -189,7 +190,8 @@ async function main() {
   ${again}`);
   }
   if (o.cmd === 'upgrade') o = upgradeOptions(o);
-  if (o.withDocNexus) { step('检查 DocNexus 依赖'); checkNodeForDocNexus(); }
+  step('检查必装组件 DocNexus 的依赖');
+  checkNodeForDocNexus();
 
   const sel = await resolveEnvs(o);
   step(`目标环境：${sel.join(' ')}`);
@@ -235,26 +237,17 @@ async function main() {
   updateGitignore(o.root, o.withCodeGraph);
   setupHome(o.root);
   recordEnv(o.root);
-  const docnexus = o.withDocNexus ? setupDocNexus(o.root, sel) : 'skipped';
-  // 升级 / 重装都刷新本项目里的 DocNexus skills 链接与 CLAUDE.md / AGENTS.md 段落
-  if (!o.withDocNexus) refreshDocNexusLinks(o.root, sel);
+  writeArtifactContext(o.root, sel);
+  if (o.withDocNexus || !docnexusConnected(o.root)) {
+    if (setupDocNexus(o.root, sel) !== 'ok') fail('必装组件 DocNexus 接入失败，安装未完成。修复上方错误后重新运行安装命令。');
+  } else refreshDocNexusLinks(o.root, sel);
   const codegraph = o.withCodeGraph ? setupCodeGraph(o.root, sel) : 'skipped';
-  let seedFailed = false;
-  // 接入 DocNexus 后文档类 skill 只从知识库取模板，所以 --with-docnexus 时一并导入（已有的不覆盖）；
-  // upgrade 时新版本可能新增了模板（缺了 skill 会停下），已接入就顺带导入缺的，不改动已有模板
-  const upgradeSeed = o.upgrading && docnexusConnected(o.root);
-  if ((o.seedTemplates || o.withDocNexus || upgradeSeed) && docnexus !== 'failed') {
-    step(upgradeSeed && !o.seedTemplates && !o.withDocNexus ? '导入新增的文档模板到 DocNexus（只新增，已有模板不动）' : '导入文档模板到 DocNexus（--seed-templates）');
-    try {
-      const r = seedTemplates(o.root, TPL_DIR, { ok, warn, version: PKG.version, skills: installedSkills(o.root), quietSkip: upgradeSeed });
-      saveTemplateRecords(o.root, r.records);
-      // upgrade 顺带的导入是尽力而为：失败只提示，不让升级本身算失败
-      const explicit = o.seedTemplates || o.withDocNexus;
-      seedFailed = explicit && r.failed.length > 0;
-      if (!explicit && r.failed.length) warn('新增模板导入失败（skills 已升级）：修复后运行 npx @rowansenne/workflow-run seed-templates 重试');
-      if (upgradeSeed && !r.seeded.length && !r.failed.length) ok('知识库里的文档模板齐全，无需导入');
-    } catch (e) { warn(e.message); seedFailed = o.seedTemplates || o.withDocNexus; }
-  }
+  step('导入文档模板到 DocNexus（只新增，已有模板不动）');
+  try {
+    const r = seedTemplates(o.root, TPL_DIR, { ok, warn, version: PKG.version, skills: installedSkills(o.root), quietSkip: true });
+    saveTemplateRecords(o.root, r.records);
+    if (r.failed.length) fail('必需文档模板导入失败，安装未完成。修复后运行 npx @rowansenne/workflow-run seed-templates 重试。');
+  } catch (e) { fail(e.message); }
 
   step('安装完成，启用方式');
   console.log('  codex     : 重启 codex 后自动发现项目级 skills（.agents/skills）；也可 /use project-review 手动加载');
@@ -267,10 +260,9 @@ async function main() {
   else warn('注意：本次未写入数据库连接。可重跑补配，或手动放置 database-query/config.json（已有的保留不动）。');
   warn('注意：md-to-wiki 的 wiki 连接（wiki-config.json）默认留空（enabled=false），未配置前 md-to-wiki 与 create-*-md-doc 的 --prd 增强不启动。');
   warn('        启用方法：填写 .agents/skills/md-to-wiki/wiki-config.json（enabled: true + base_url + api_token），或接入对应环境的 wiki MCP。重跑不会覆盖已填写的配置。');
-  if (docnexus === 'ok') ok('DocNexus 已接入：dev / project-review 会按 docnexus-recall 查项目约定；文档类 skill 只从 workflow-run/docnexus/library/templates/ 取模板；任何写入 DocNexus 的操作都需你授权。');
+  ok('DocNexus 已接入：dev / project-review 会按 docnexus-recall 查项目约定；文档类 skill 只从 workflow-run/docnexus/library/templates/ 取模板；任何写入 DocNexus 的操作都需你授权。');
   // 已接入 DocNexus：缺模板时文档类 skill 会停下来要求导入；默认模板有新版时提示更新或合并
   if (docnexusConnected(o.root)) reportTemplateStatus(o.root);
-  if (docnexus === 'failed') warn('注意：DocNexus 接入失败（见上方输出），其他 skills 不受影响；修复后可重跑（加 --with-docnexus）。');
   if (codegraph === 'failed') warn('注意：CodeGraph 接入失败（见上方输出），其他 skills 不受影响；skills 会退回 grep / 读文件；修复后可重跑（加 --with-codegraph）。');
   const keep = '（skills 目录里的文件以安装包为准；项目定制请放到 workflow/profile.json、DocNexus（文档模板只能在这里定制）或 CLAUDE.md / AGENTS.md）';
   if (report.overwritten.length || report.removed.length) {
@@ -283,8 +275,7 @@ async function main() {
     ok(`${report.unlistedDirs.join('、')} 里没有安装清单，${report.unlisted.length} 个和新版不同的文件已备份到 ${report.backupDir}/ 后覆盖（无从判断是否手改过）`);
   }
   console.log('先运行 /workflow profile 填写项目画像；说明见 workflow-run README。');
-  // skills 已装好，但显式要求的 DocNexus 未接入：返回非 0 便于自动化感知
-  return docnexus === 'failed' || codegraph === 'failed' || seedFailed ? 1 : 0;
+  return codegraph === 'failed' ? 1 : 0;
 }
 
 main().then((code) => process.exit(code), (e) => {

package/code-graph/SKILL.md.tpl

@@ -5,14 +5,9 @@ description: "Answer structural questions about this project's source code from
 
 # Code Graph
 
-在 [CodeGraph](https://github.com/colbymchenry/codegraph) 代码图谱之上回答「代码结构」类问题：影响面、调用方、入口、MQ、定时任务、SQL 涉及的表。脚本 `scripts/cg.mjs` 直接调用 CodeGraph 的库，并补上它看不到的 Java / Spring 关联。只读：不建索引、不改代码。
-
-## 先看能不能用
+**开工能力**：先运行 `node <skills>/workflow/scripts/resolve.mjs status`，按 `<skills>/workflow/references/capabilities.md` 选择本轮能力与模板；同一项目链路复用已有快照，失败统一按该规则处理。
 
-运行 `node <skills>/code-graph/scripts/cg.mjs status`：
-
-- `indexed: false` → 本项目没有 `.codegraph/` 索引。**不要替用户建索引**；告诉用户可以运行 `codegraph init`（或重跑 workflow-run 加 `--with-codegraph`），这次改用 grep / 读文件回答，并说明「未使用代码图谱」。
-- `library` 里有 `error` → 找不到库或 Node 低于 22.5：`impact` / `entry` 不可用，改用 CodeGraph 的 CLI（`codegraph impact` / `callers` / `explore`，见 `<skills>/workflow/references/codegraph.md`）；`mq` / `jobs` / `tables` 只扫源码，照常可用。
+在 [CodeGraph](https://github.com/colbymchenry/codegraph) 代码图谱之上回答「代码结构」类问题：影响面、调用方、入口、MQ、定时任务、SQL 涉及的表。脚本 `scripts/cg.mjs` 直接调用 CodeGraph 的库，并补上它看不到的 Java / Spring 关联。只读：不建索引、不改代码。
 
 ## 命令
 

package/create-release-md-doc/SKILL.md.tpl

@@ -5,6 +5,8 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
 
 # Create Release MD Doc
 
+**开工能力**：先运行 `node <skills>/workflow/scripts/resolve.mjs status`，按 `<skills>/workflow/references/capabilities.md` 选择本轮能力与模板；同一项目链路复用已有快照，失败统一按该规则处理。
+
 对比开发分支与主分支的 diff，按项目自己的上线方案模板生成 Markdown。模板不随 skills 提供：第一次使用时请用户给一份团队现有的上线方案作样例来创建（见 Step 3）。技术方案回答「怎么开发」，上线方案回答「怎么上线」。
 
 ## Command Format
@@ -25,11 +27,13 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
 1. `git rev-parse --is-inside-work-tree` 为 `true`，否则停。
 2. 两个分支都能 `git rev-parse --verify`（或 `origin/<branch>`）；不存在 → 列出候选让用户挑，停。
 3. 读 `workflow/profile.json`：发布平台、Region、配置中心、定时任务注解、是否需要数据评审都取自这里；未配置的写「待填写」，**不要沿用其他项目的取值**。
-4. DocNexus 可用时运行 `node <skills>/workflow/scripts/knowledge.mjs create-release-md-doc --match <模块名 / 业务名词> --query "<一句话：本次上线改了什么>"`（模块名取分支名或 diff 涉及的模块），看以往上线方案沉淀的风险、回滚要点与技术方案沉淀；相关的在文档对应章节引用 `workflow-run/docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。未接入就跳过。
+4. 运行 `node <skills>/workflow/scripts/knowledge.mjs create-release-md-doc --match <模块名 / 业务名词> --query "<一句话：本次上线改了什么>"`（模块名取分支名或 diff 涉及的模块），看以往上线方案沉淀的风险、回滚要点与技术方案沉淀；相关的在文档对应章节引用 `workflow-run/docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。
+
+**完整流程状态**：Step 0 通过后确定需求名、绑定目标 dev 分支，按 `<skills>/workflow/references/runs.md` 用 kind `release` 创建／恢复运行；带上 `--branch <dev分支>`，L0～L4 对应 Step 0～4。已完成步骤、PRD 跳过原因、模板等待／阻塞和证据都写 checkpoint；缺模板停下时不能丢失进度。Step 4 文档写完、自检和交付摘要完成后，将 L4 标 completed，再 complete 保存“已完成”与完成时间；Step 5 的可选下一步另行处理，不把 dev 的已完成记录覆盖成文档运行。
 
 ### Step 1 — PRD（仅传入 `--prd` 时）
 
-按 `references/prd-fetch.md` 判断 wiki 是否可用并拉取 PRD（不可用 → 告知「wiki 连接未配置，PRD 增强已跳过」，继续无 PRD 流程），再按 `references/prd.md` 抽取本文档需要的字段并做对齐校验。PRD 任何环节失败都只回退，不中止。
+按本轮 wiki 通道与 `references/prd-fetch.md` 拉取 PRD，再按 `references/prd.md` 抽取本文档需要的字段并做对齐校验。PRD 任何环节失败都只回退，不中止。
 
 ### Step 2 — 采集 diff 并抽取事实
 
@@ -37,10 +41,7 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
 
 ### Step 3 — 选模板并填充
 
-- 模板：在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template create-release-md-doc template.md`（`<skills>` 是本 skill 所在的 skills 目录，如 `.agents/skills`），读输出的 `path`，并把 `source` 写进元数据行。上线方案模板**不随 skills 提供**，由各团队按自己 wiki 上的格式创建：
-  - 退出码 2 且 `on_demand: true` → 还没有创建模板：**停下这一步**，按 `<skills>/workflow/references/templates.md`「创建模板」请用户给一份团队现有的上线方案作样例，生成模板、用户确认后保存到输出的 `expected`，再继续。不要自己编一份通用模板凑数。
-  - 退出码 2 且 `need_docnexus: true` → 未接入 DocNexus：上线方案模板只保存在 DocNexus 里，**停下这一步**告诉用户先重跑 workflow-run 并加 `--with-docnexus` 接入，再按「创建模板」创建。不要另存到别处。
-  - 退出码 2 的其他情况 → 按输出的 `hint` 处理。
+- 模板：在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template create-release-md-doc template.md`（`<skills>` 是本 skill 所在的 skills 目录，如 `.agents/skills`），读输出的 `path`，并把 `source` 写进元数据行。模板缺失统一按 `workflow/references/templates.md` 创建或导入。
   - 用户要修改、重新生成或换一份上线方案模板时，按 `<skills>/workflow/references/templates.md`「修改模板」用 `template.mjs` 处理（模板别名 `release`；按样例重做用 `draft release --from <样例>`），保存写入 DocNexus 知识库。
 - 填充：模板的章节和编号因团队而异，**按章节含义**放事实，不按编号。下表是事实的来源，放进模板里含义对应的章节；模板里没有对应章节的事实不擅自加章节，在交付摘要里列出「模板中没有位置的事实」；模板有、但 diff 和 PRD 都给不出内容的章节写「待补充」。
 
@@ -80,8 +81,8 @@ description: "Generate a Markdown release/deployment plan (上线方案) from th
 ### Step 5 — 后续（都需要用户同意）
 
 - 发布到 wiki：`/md-to-wiki <文档路径> [pageId]`（发布过的文档有发布记录，可省略 pageId）。
-- 模板回写：用户对生成的文档做了结构性调整（新增 / 删除 / 重排章节、改表格列）时，问要不要同步回模板：未接入 DocNexus 时按「修改模板」用 `template.mjs draft / check / save release` 改（用户确认后保存）；已接入时按 `<skills>/workflow/references/templates.md`「模板随知识库更新」提议同步回模板。
-- 沉淀到 DocNexus（DocNexus 可用时，判定见 `<skills>/workflow/SKILL.md`「增强能力探测」）：列出值得长期记住的决策、配置 / 依赖变化、风险与坑，**询问用户**；同意后按 DocNexus 入口 skill `docnexus` 的 capture 流程写入，分类用 `node <skills>/workflow/scripts/resolve.mjs category create-release-md-doc` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」），并回报 `workflow-run/docnexus/library/<path>`。只沉淀确认过的事实，不沉淀「待补充」「待人工确认」的推断。未检测到 DocNexus 就跳过，不提示安装。
+- 模板回写：用户对生成的文档做了结构性调整（新增 / 删除 / 重排章节、改表格列）时，问要不要同步回模板：按 `<skills>/workflow/references/templates.md`「模板随知识库更新」提议同步回模板。
+- 沉淀到 DocNexus：列出值得长期记住的决策、配置 / 依赖变化、风险与坑，**有值得记的才询问用户**，没有就跳过；同意后按 DocNexus 入口 skill `docnexus` 的 capture 流程写入，分类用 `node <skills>/workflow/scripts/resolve.mjs category create-release-md-doc` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」），并回报 `workflow-run/docnexus/library/<path>`。只沉淀确认过的事实，不沉淀「待补充」「待人工确认」的推断。
 
 ## Red Flags — STOP
 

package/create-tech-md-doc/SKILL.md.tpl

@@ -5,6 +5,8 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
 
 # Create Tech MD Doc
 
+**开工能力**：先运行 `node <skills>/workflow/scripts/resolve.mjs status`，按 `<skills>/workflow/references/capabilities.md` 选择本轮能力与模板；同一项目链路复用已有快照，失败统一按该规则处理。
+
 对比开发分支与主分支的 diff，按项目自己的技术方案模板生成 Markdown。模板不随 skills 提供：第一次使用时请用户给一份团队现有的技术方案作样例来创建（见 Step 3）。
 
 ## Command Format
@@ -24,11 +26,13 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
 1. `git rev-parse --is-inside-work-tree` 为 `true`，否则停。
 2. 两个分支都能 `git rev-parse --verify`（或 `origin/<branch>`）；不存在 → 列出 `git branch -a -i --list "*<关键词>*"` 的候选让用户挑，停。
 3. 读 `workflow/profile.json`：发布平台、Region、配置中心、定时任务注解、是否需要数据评审都取自这里；未配置的写「待填写」，**不要沿用其他项目的取值**。
-4. DocNexus 可用时运行 `node <skills>/workflow/scripts/knowledge.mjs create-tech-md-doc --match <模块名 / 业务名词> --query "<一句话：本次改动做了什么>"`（模块名取分支名或 diff 涉及的模块），看以往技术方案沉淀的决策与约定、相关开发沉淀；相关的在文档对应章节引用 `workflow-run/docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。未接入就跳过。
+4. 运行 `node <skills>/workflow/scripts/knowledge.mjs create-tech-md-doc --match <模块名 / 业务名词> --query "<一句话：本次改动做了什么>"`（模块名取分支名或 diff 涉及的模块），看以往技术方案沉淀的决策与约定、相关开发沉淀；相关的在文档对应章节引用 `workflow-run/docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。
+
+**完整流程状态**：Step 0 通过后确定需求名、绑定目标 dev 分支，按 `<skills>/workflow/references/runs.md` 用 kind `tech` 创建／恢复运行；带上 `--branch <dev分支>`，T0～T4 对应 Step 0～4。已完成步骤、PRD 跳过原因、模板等待／阻塞和证据都写 checkpoint；缺模板停下时不能丢失进度。Step 4 文档写完、自检和交付摘要完成后，将 T4 标 completed，再 complete 保存“已完成”与完成时间；Step 5 的可选下一步另行处理，不把 dev 的已完成记录覆盖成文档运行。
 
 ### Step 1 — PRD（仅传入 `--prd` 时）
 
-按 `references/prd-fetch.md` 判断 wiki 是否可用并拉取 PRD（不可用 → 告知「wiki 连接未配置，PRD 增强已跳过」，继续纯 diff 流程），再按 `references/prd.md` 抽取本文档需要的字段并做对齐校验。PRD 任何环节失败都只回退，不中止。
+按本轮 wiki 通道与 `references/prd-fetch.md` 拉取 PRD，再按 `references/prd.md` 抽取本文档需要的字段并做对齐校验。PRD 任何环节失败都只回退，不中止。
 
 ### Step 2 — 分层采集 diff 并抽取事实
 
@@ -36,10 +40,7 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
 
 ### Step 3 — 选模板并填充
 
-- 模板：在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template create-tech-md-doc template.md`（`<skills>` 是本 skill 所在的 skills 目录，如 `.agents/skills`），读输出的 `path`，并把 `source` 写进元数据行。技术方案模板**不随 skills 提供**，由各团队按自己 wiki 上的格式创建：
-  - 退出码 2 且 `on_demand: true` → 还没有创建模板：**停下这一步**，按 `<skills>/workflow/references/templates.md`「创建模板」请用户给一份团队现有的技术方案作样例，生成模板、用户确认后保存到输出的 `expected`，再继续。不要自己编一份通用模板凑数。
-  - 退出码 2 且 `need_docnexus: true` → 未接入 DocNexus：技术方案模板只保存在 DocNexus 里，**停下这一步**告诉用户先重跑 workflow-run 并加 `--with-docnexus` 接入，再按「创建模板」创建。不要另存到别处。
-  - 退出码 2 的其他情况 → 按输出的 `hint` 处理。
+- 模板：在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template create-tech-md-doc template.md`（`<skills>` 是本 skill 所在的 skills 目录，如 `.agents/skills`），读输出的 `path`，并把 `source` 写进元数据行。模板缺失统一按 `workflow/references/templates.md` 创建或导入。
   - 用户要修改、重新生成或换一份技术方案模板时，按 `<skills>/workflow/references/templates.md`「修改模板」用 `template.mjs` 处理（模板别名 `tech`；按样例重做用 `draft tech --from <样例>`），保存写入 DocNexus 知识库。
 - 填充：模板的章节和编号因团队而异，**按章节含义**放事实，不按编号。下表是事实的来源，放进模板里含义对应的章节；模板里没有对应章节的事实不擅自加章节，在交付摘要里列出「模板中没有位置的事实」；模板有、但 diff 和 PRD 都给不出内容的章节写「待补充」。
 
@@ -78,9 +79,9 @@ description: "Generate a Markdown technical design doc (技术方案) from the d
 ### Step 5 — 后续（都需要用户同意）
 
 - 发布到 wiki：`/md-to-wiki <文档路径> [pageId]`（发布过的文档有发布记录，可省略 pageId）。
-- 模板回写：用户对生成的文档做了结构性调整（新增 / 删除 / 重排章节、改表格列）时，问要不要同步回模板：未接入 DocNexus 时按「修改模板」用 `template.mjs draft / check / save tech` 改（用户确认后保存）；已接入时按 `<skills>/workflow/references/templates.md`「模板随知识库更新」提议同步回模板。
+- 模板回写：用户对生成的文档做了结构性调整（新增 / 删除 / 重排章节、改表格列）时，问要不要同步回模板：按 `<skills>/workflow/references/templates.md`「模板随知识库更新」提议同步回模板。
 - 要上线：`/create-release-md-doc <dev> <main> --tech <文档路径>` 复用本文档的事实。
-- 沉淀到 DocNexus（DocNexus 可用时，判定见 `<skills>/workflow/SKILL.md`「增强能力探测」）：列出值得长期记住的决策、约定、配置 / 依赖变化、风险，**询问用户**；同意后按 DocNexus 入口 skill `docnexus` 的 capture 流程写入，分类用 `node <skills>/workflow/scripts/resolve.mjs category create-tech-md-doc` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」），并回报 `workflow-run/docnexus/library/<path>`。只沉淀确认过的事实，不沉淀「待补充」「待人工确认」的推断。未检测到 DocNexus 就跳过，不提示安装。
+- 沉淀到 DocNexus：列出值得长期记住的决策、约定、配置 / 依赖变化、风险，**有值得记的才询问用户**，没有就跳过；同意后按 DocNexus 入口 skill `docnexus` 的 capture 流程写入，分类用 `node <skills>/workflow/scripts/resolve.mjs category create-tech-md-doc` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」），并回报 `workflow-run/docnexus/library/<path>`。只沉淀确认过的事实，不沉淀「待补充」「待人工确认」的推断。
 
 ## Red Flags — STOP
 

package/database-query/SKILL.md.tpl

@@ -5,6 +5,8 @@ description: "Query the project database via SQL and report results. Use when th
 
 # Database Query
 
+**开工能力**：先运行 `node <skills>/workflow/scripts/resolve.mjs status`，按 `<skills>/workflow/references/capabilities.md` 选择本轮能力与模板；同一项目链路复用已有快照，失败统一按该规则处理。
+
 查询本项目数据库并结构化返回结果。默认只读；只读连接上**任何**写操作都不执行。
 
 ## 连接配置（config.json）

package/database-query/skill.json

@@ -1,10 +1,10 @@
 {
   "name": "database-query",
   "order": 4,
-  "requires": [],
-  "optional": [
+  "requires": [
     "workflow"
   ],
+  "optional": [],
   "userFiles": {
     "config.json": null,
     "references/schema.md": null

package/dev/SKILL.md.tpl

@@ -1,173 +1,99 @@
 ---
 name: dev
-description: "Implement a feature or fix a bug in this project end to end: understand the requirement, study existing code, clarify open decisions with the user in rounds, plan at the right size, implement in small verified steps, run tests, self-review the diff with project-review, and deliver a summary with config/SQL checklists. Use when the user asks to develop, implement, add, change or fix something in the codebase — including concrete refactors that touch several classes (swap a type such as Date → LocalDateTime, rename, replace an API) followed by running tests — or invokes /dev <需求> or /dev --bug <现象>. Trigger phrases: 帮我开发 / 实现这个需求 / 加个接口 / 改一下这个逻辑 / 把 X 改成 Y / 重构一下 / 改完跑一下测试 / 修这个 bug / 排查并修复 / 线上报错了帮我修 / implement this feature / fix this bug. Not for pure code review (project-review), SQL lookups (database-query) or doc generation (create-tech-md-doc / create-release-md-doc)."
+description: "Implement a feature or fix a bug in this project end to end: understand the requirement, study existing code, clarify open decisions with the user in rounds, plan at the right size, implement in small verified steps, run tests, have an independent subagent review and write a report, then let the user choose fixes or delivery with config/SQL checklists. Use when the user asks to develop, implement, add, change or fix something in the codebase — including concrete refactors that touch several classes (swap a type such as Date → LocalDateTime, rename, replace an API) followed by running tests — or invokes /dev <需求> or /dev --bug <现象>. Trigger phrases: 帮我开发 / 实现这个需求 / 加个接口 / 改一下这个逻辑 / 把 X 改成 Y / 重构一下 / 改完跑一下测试 / 修这个 bug / 排查并修复 / 线上报错了帮我修 / implement this feature / fix this bug. Not for pure code review (project-review), SQL lookups (database-query) or doc generation (create-tech-md-doc / create-release-md-doc)."
 ---
 
 # Dev
 
-把一个开发需求或 bug 从「理解」推进到「可交付」。本 skill 负责编排，复用同项目的其他 skill：
+把需求或缺陷推进到可交付。`/dev <需求 | PRD>` 为功能开发，`/dev --bug <现象>` 为缺陷修复；自然语言按同样意图路由。
+进入每个阶段前，读取下面指向的 reference 对应小节；不在开工时一次加载全部方法说明。
 
-| 环节 | 复用 | 不可用时 |
-|---|---|---|
-| 需求背景 | wiki 中的 PRD（按 `references/prd-fetch.md` 拉取） | 只用对话中的需求描述 |
-| 项目约定 / 历史决策 | DocNexus（`docnexus-recall` skill） | 读 `CLAUDE.md` / `AGENTS.md` 与代码 |
-| 读代码 / 调用链 / 影响面 | CodeGraph（见 `<skills>/workflow/references/codegraph.md`） | grep / 读文件 |
-| 涉及哪些表 / 实际表结构 / 数据核对 | `workflow/scripts/tables.mjs` 定位表 → `database-query`（`query.mjs --schema --tables … --indexes`，只读） | 读 `schema.md` 与 DDL 脚本，注明「未与实际库核对」 |
-| 自审 | `project-review`（随 dev 一起安装；内部调用的边界见 F7） | — |
-| 交付文档 | `create-tech-md-doc` / `create-release-md-doc` | 只在对话中汇总 |
+## 门禁
 
-## Command Format
+- 开工先运行 `node <skills>/workflow/scripts/resolve.mjs status`；DocNexus 必装，不可用先修复。可选增强复用 `<skills>/workflow/references/capabilities.md` 的本轮快照。
+- 先确定工作分支、已有改动的归属与需求名；切分支重新查询绑定，不替用户丢弃已有改动。
+- 规模由 agent 判定并说明，不询问规模确认；M / L 的需求理解和方案须用户确认后再实现，权限 / 资金至少按 M。
+- S 快速通道须用户明确同意，且 ≤3 文件、无配置 / SQL / 对外接口 / 表结构 / 权限 / 资金变更，且没有已确认的业务决定；具体资格见 F4。
+- 快速通道仍编译、测试、当前会话审查，但不 bind、不建运行、不落方案 / 审查 / 交付文档；超限或用户要求落盘先停，回 F4（bug 回 B4）补方案。
+- 完整流程每轮审查落 `review.md`，交报告后等待明确选择修复或交付；选择交付前不创建或更新 `delivery.md`。
+- 修复后必须验证、复审并再次等选择；严重遗留风险须说明并取得明确接受，不能把一般的“交付”当作接受风险。
+- 交付选择不授权提交、推送、发布或知识写入；没有值得沉淀的知识不询问，有则先取得授权。
 
-```
-/dev <需求描述 | PRD pageId/url>          # 功能开发（默认）
-/dev --bug <现象 | 报错 | 日志片段>        # 缺陷修复
-```
+## Step 0 — 前置检查（两种模式共用）
 
-没有斜杠命令时按用户意图判断模式：描述的是「要新增/改变的行为」→ 功能开发；描述的是「现在的行为不对」→ 缺陷修复。
+先读 [preflight.md](references/preflight.md)：运行 `resolve.mjs profile`、`git status --short`，确定工作分支后运行 `requirement.mjs which`；确认画像、改动归属、需求名、审查方式与构建 / 相关测试基线。结果带入本次上下文，给不出需求名或说不清任务时停下。
+上述 workflow 脚本缩写均用 `node <skills>/workflow/scripts/<脚本>` 在项目根执行；终端写法沿用能力快照的 env。
 
-## Step 0 — 前置检查（两种模式共用）
+## 完整流程的运行状态
 
-1. **项目画像**：运行 `node <skills>/workflow/scripts/resolve.mjs profile`，读输出的 `profile`、`empty`（空字段列表）与 `toolchain`（开发环境配置，见 `workflow` skill）。本 skill 用到 `main_branch`、`build`、`test`、`test_single`（`{target}` 替换为测试类或文件）、`lint`、`config_center`、`notes`。
-   - 需要的字段为空 → 按 `<skills>/workflow/references/profile.md`「填写与更新」的步骤推断，经用户确认后写回；用户不确认就只在本次使用，不落盘。
-   - **开发环境配置**：`toolchain.configured` 为 true 时，编译 / 测试按它跑（JDK 用 `java_home`、Maven 用 `maven.settings` / `maven.repository`，写命令时把对应的 `env_vars`（如 `JAVA_HOME`）带上，例如 `JAVA_HOME=<值> <profile.build>`）。构建或测试失败且像是环境问题（找不到 java、依赖下载不下来、版本不对）时，先运行 `node <skills>/workflow/scripts/resolve.mjs env --check`：字段 `exists: false` 或带 `unset_vars` 就是环境没配对，把 `resolved` 和 `current`（本机实际值）一起给用户看，问清楚再继续，**不要自己改画像**。配过但本机对不上时属于个人差异，按 `references/profile.md` 写进 `profile.local.json`。
-2. **工作区状态**：`git status --short` 与当前分支。
-   - 有未提交改动或未跟踪文件 → 列出这些文件，**问用户哪些属于本需求**（例如用户先手写了一部分，让你接着做）；可以和后面的澄清问题一起问。不要替用户 stash / 丢弃。
-     - 属于本需求的：和你之后的改动同等对待，影响面、相关测试、自审、交付说明「改动」节都纳入。
-     - 不属于的：照常在测试里跑到（测试跑的是整个工作区），但不算本次改动——自审在这些文件里发现的问题写进「范围外发现」，交付说明单独列出，提交时不 add。同一个文件里两边都改了的，告诉用户，自审只按本需求那部分下结论。
-   - 当前在主分支（`profile.main_branch`）上 → 建议先建特性分支，用户同意后再建。
-3. **增强能力探测**：运行 `node <skills>/workflow/scripts/resolve.mjs status`，按输出的 `wiki` / `docnexus` / `database` 判断是否可用（wiki MCP 脚本探测不到，另看当前环境有没有 wiki 工具）。都不阻塞，不可用就跳过对应增强，并在交付说明中注明。
-4. **基线**：动代码前运行一次 `profile.build`，再跑和本需求相关的测试（`profile.test_single` 或相关模块，不必全量），记下已经失败的测试和编译错误。之后只对新增的失败负责：已有失败不顺手修，写进交付说明「开工前已有的失败」。跑不了就记「未跑基线」和原因。
+确定工作分支后先 `run.mjs show`；恢复时核对 context、代码与证据，不能把“继续”当作交付选择。
+非快速通道在 F4 / B4 首次落盘前 bind，再 `run.mjs start --kind feature|bug --size <规模> --input <checkpoint.json>`，补记真实完成的前置步骤。
+每步完成、等待、阻塞和结束会话前 save；修复回 F5 / B4，交付进 F8 / B5。具体协议读 `<skills>/workflow/references/runs.md`。
+交付、自检、摘要与反馈处理后，末步标 completed，再 `run.mjs complete`，保存 completed（已完成）和 completed_at；已完成运行不覆盖。
 
 ## 功能开发流程
 
 ### F1 — 理解需求
 
-- 需求来源是 PRD pageId/URL → 按 `references/prd-fetch.md` 拉取并提炼；wiki 不可用 → 请用户贴出关键内容。
-- DocNexus 可用 → 先运行 `node <skills>/workflow/scripts/knowledge.mjs dev --match <模块名 / 业务名词> --query "<一句话需求>"`，看以往开发沉淀、技术方案和反复出现的审查问题里有没有相关的（`--query` 在这些分类内按正文 recall）。引用 `workflow-run/docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。
-- 先在心里列出初版 **需求要点 + 验收标准**（可验证的行为，而不是实现手段）和还没定的决定，带进 F2 查事实、F3 澄清。
+读 [planning.md 的 F1](references/planning.md)；运行 `node <skills>/workflow/scripts/knowledge.mjs dev --match <模块> --query "<需求>"`，按需拉 PRD，形成需求要点、验收标准与未定决定。
 
 ### F2 — 现状调研
 
-- 从入口（Controller / Handler / CLI / 页面）沿调用链读到持久层，理清数据流；不凭文件名猜内容。CodeGraph 可用时（`resolve.mjs status` 的 `codegraph.ok`）先用 `codegraph_explore` / `codegraph explore "<问题>"` 一次拿到链路上的源码和调用路径，再按需补读；Spring 注入、MyBatis XML、MQ、配置 key 这些图谱看不到的照常 grep（见 `<skills>/workflow/references/codegraph.md`）。
-- 找到同类功能的既有实现，作为风格与结构的参照（命名、分层、异常、日志、事务、DTO 转换方式）。
-- 涉及数据库 → 按 `<skills>/workflow/references/tables.md` 先确定涉及哪些表（`tables.mjs --files <读到的实体 / Mapper>`），数据库已配置时用 `query.mjs --schema --tables <表> --indexes` 只读拉取实际字段、索引与行数；方案里的字段名、类型、索引和 DDL 以查到的为准，不凭实体类推测。
+读 [planning.md 的 F2](references/planning.md)；按本轮能力沿调用链读代码，涉及表时用 `tables.mjs --files <文件>` 定位；事实与证据进入方案依据。
 
 ### F3 — 需求澄清
 
-按 `references/clarify.md` 分轮提问：把需求拆成决策树（行为、边界、异常、兼容、权限、数据、范围），**事实自己查**（代码、表结构、PRD、DocNexus），**决定交给用户**；每轮把现在就能问的问题一次问完，编号并给出推荐答案和依据，等用户回答后再问下一轮，直到没有被默默假设的决定。
-
-| 情况 | 做法 |
-|---|---|
-| S 规模且 F2 后没有未定的决定 | 跳过需求澄清提问，写明本次的理解和假设；仍须按 F4 确认规模 |
-| 只有一两个小决定 | 问一轮即可 |
-| M / L 规模，或用户说「拷问一下 / grill me / 先把需求问清楚」 | 按轮问到前沿为空，输出需求要点、验收标准、不在本次范围、已确认的决定，**等用户确认理解一致**再进 F4 |
-
-不要边写代码边问：实现中才发现的新决定，停下来按同样格式问，再继续。
-
-### F4 — 方案（按规模分级）
-
-| 规模 | 判定 | 做法 |
-|---|---|---|
-| **S** | ≤3 个文件，无接口签名 / 表结构 / 配置项变更，不涉及权限 / 资金 | 用户确认规模后，在对话中列改动步骤并开始 |
-| **M** | 新增或修改接口、配置项、少量表字段 | 在对话中给出简要方案（方案模板的精简版），**等用户确认后再写代码** |
-| **L** | 新模块、跨服务、表结构较大变更、数据迁移 | 按方案模板写方案文档落盘（见 Artifact Location），用户确认后再写代码；完成后建议用 `create-tech-md-doc` 生成正式技术方案 |
-
-规模拿不准时按大一级处理。涉及权限（鉴权、角色、数据可见范围）或资金（金额计算、扣款、退款、对账）的改动，文件再少也至少按 M：需求理解（F3）和方案都要用户确认。
-
-**规模确认（S / M / L 都必做，含快速通道）**：判定后向用户说明推荐规模、依据（预计改动文件 / 模块、接口 / 数据 / 配置变化及风险），以及对应流程（是否走快速通道、方案与交付说明是否落盘），明确询问是否按该规模处理。**等用户明确确认后，再按该规模推进后续流程、绑定需求或写代码**；只告知判定结果或默认选中推荐项不算确认。可以与 F3 的理解确认或简要方案确认在同一轮提出，但必须明确列出规模并收到确认；本轮对话中已明确确认的同一规模不重复询问。用户调整范围或实现中发现规模变化时，说明变化依据，确认新规模后再继续。规模确认属于流程选择，不算 F3 的业务决定，不影响 S 规模快速通道资格。
+读 [clarify.md](references/clarify.md) 与 [planning.md 的 F3](references/planning.md)；事实自己查、决定交用户；输出验收标准、范围和已确认决定，实现中新决定先停下来澄清。
 
-**M / L 规模先定需求名**：用户确认规模、确定要落盘时，按 Artifact Location 运行 `requirement.mjs which`，当前分支没绑定需求就在这一轮问用户这个需求叫什么（可以和规模确认、澄清问题一起问），之后的方案、交付、审查、技术方案、上线方案都归到这个需求下。
+### F4 — 方案（落盘只看是否快速通道，写法按规模）
 
-**S 规模快速通道**：用户已确认 S 规模，且改动**不涉及**配置项、SQL / DDL、对外接口（HTTP 接口签名、MQ 消息体、对外 DTO）、表结构、权限、资金，也没有 F3 中确认过的业务决定 → 走快速通道：F5～F7 照常（编译、测试、自审都不省），F8 只在对话里交付，不落盘交付说明、不问 DocNexus 沉淀（见 F8「快速通道交付」）。规模确认时说明「按快速通道处理，不落盘交付说明」。实现中一旦碰到上面任何一项、改动超过 3 个文件，或用户要求落盘 → 退出快速通道，按完整 F8 交付；重新评估后规模变化的，先确认新规模再继续。小改动也要走完整流程是用户绕开 dev 的主要原因，所以只在上面这些会影响上线和团队的情况下才落盘。
-
-方案模板：在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`，读输出的 `path`；退出码 2（已接入 DocNexus 但缺模板）时停下并按 `hint` 处理。L 规模的方案文档落盘后运行 `node <skills>/workflow/scripts/lint-doc.mjs <方案路径> --skill dev` 自检，再请用户确认。
+先读 [planning.md 的 F4](references/planning.md) 再选择快速通道；完整流程用 `requirement.mjs path plan` 写 `plan.md` 并 lint / sync，S / M 简版、L 完整版；M / L 确认后继续。
 
 ### F5 — 实现
 
-- **小步推进**：按逻辑分步实现，一步改完（或改了公共签名、跨了模块）运行 `profile.build`（没有则用对应构建工具的编译命令）确认通过，再进入下一步。不必每改一个文件就编译，代码没变时不重复跑。
-- **改动前看影响面**：要改公共方法、接口签名、DTO 字段时，先 `node <skills>/code-graph/scripts/cg.mjs entry <Class.method>`（code-graph skill；退出码 2 时用 grep），把会被波及的入口和调用方纳入本次改动或写进交付说明。
-- **贴合现有代码**：沿用参照实现的写法；不顺手重构、不改无关代码、不升级依赖。看到范围外的问题记进交付说明，不在本次修。
-- **配置**：新增配置项记入配置清单（key、位置、用途、建议默认值、上线前需下发的环境），按 `profile.config_center` 与审查清单的配置维度处理（清单路径用 `node <skills>/workflow/scripts/resolve.mjs template project-review checklist.md` 取，接入 DocNexus 时是团队维护的版本）。
-- **数据库变更**：DDL / 数据修正写成 SQL 脚本放进项目约定的目录（没有约定则放进交付说明），**不在任何环境直接执行**。写之前按 `<skills>/workflow/references/tables.md` 核对实际表结构：要加的列 / 索引是否已存在、新查询条件有没有索引、表有多大（大表 DDL 写进上线注意事项）。
-- **敏感信息**：不硬编码密钥、密码、内网地址；日志不打印敏感字段。
+读 [implementation.md 的 F5](references/implementation.md)；小步修改、小步运行 `profile.build`，公共签名先看影响面；改动、配置清单与 SQL 脚本进入交付依据。
 
 ### F6 — 验证
 
-- 按验收标准补充或更新单元测试 / 集成测试，测试放在项目既有测试目录、沿用既有测试框架。
-- **验收项对应到证据**：F1 / F3 的每条验收标准写明靠哪个测试或手动操作验证、结果如何；没有测试也没法操作的标「未验证」并写原因。交付说明「验证」节的表格按这个填，快速通道在对话里列同样的对应。
-- 先跑相关测试（`profile.test_single`，或代码图谱的 `impact` 选出的测试），修到通过；最后跑一次 `profile.test` 全量（之后又改了代码就再跑）。有 `profile.lint` 时一并运行。全量里出现、基线没跑到的失败，先看失败的测试是否碰到本次改动的代码，确认无关的按已有失败记录并写明依据。代码图谱可用时相关测试取自 `node <skills>/code-graph/scripts/cg.mjs impact --base <main_branch>` 输出的 `tests`；`impact` 的 `entry_points`、`sql`、`config_keys` 写进交付说明（受影响的接口 / 消费者 / 定时任务、表、配置）。改动碰到 SQL、实体或 DDL 时运行 `node <skills>/workflow/scripts/tables.mjs --base <main_branch>`，对其中的表再核对一次实际表结构（见 `<skills>/workflow/references/tables.md`），结果写进交付说明的 SQL 节。
-- 如实报告结果：失败就给出失败输出并继续修；环境跑不了（缺依赖、缺中间件）就明确写「未验证」以及用户该如何验证。**不得声称未运行的测试已通过。**
+读 [implementation.md 的 F6](references/implementation.md)；执行相关测试、`profile.test` 与已配置的 lint；记录“验收项 → 测试或操作 → 结果”，已有失败与未验证项如实保留。
 
-### F7 — 自审
+### F7 — 审查、报告与用户选择
 
-- 按 `project-review` skill 审本次改动，范围用 `node <skills>/workflow/scripts/review-scope.mjs --base <main_branch>`：分支已有的提交、未提交的改动和未跟踪的新文件一起列出。Step 0 确认不属于本需求的文件用 `--exclude <文件,文件>` 排除，它们不计入本次结论（见 Step 0「工作区状态」）；之后 project-review 的 `rules`、`locate.mjs` 都带同样的参数。
-- 只走 project-review 的第 1～6 步（范围与深度、建立理解、对比、过清单、影响面、复核）；**跳过第 7 步落盘报告、第 8 步 DocNexus 询问和第 9 步运行反馈**——结论由 dev 在 F8 统一交付，沉淀只在 F8 问一次，反馈也只由 dev 记一行。用户要求单独的审查报告时，再按 project-review 的第 7 步和产物规范落盘。
-- 交给 F8 的是：问题表（文件:行号、严重级别、触发条件、复核结果）、影响面、未覆盖与待确认。
-- CRITICAL / HIGH 必须修掉后重新跑 F6；MEDIUM / LOW 修掉或写进交付说明。
+先读 [delivery.md 的 F7](references/delivery.md)，完整流程按 project-review 第 1～7 步审查；优先独立子 agent，无则当前会话并如实署名。完整流程落报告、交用户、等修复或交付选择；内部审查不另起运行、不单独沉淀或记反馈。快速通道只在当前会话审查。
 
 ### F8 — 交付
 
-**快速通道交付**（见 F4「S 规模快速通道」）：不落盘、不跑 lint、不问 DocNexus 沉淀。对话里给：结果一句话、改动文件、验证（验收项 → 测试 / 操作 → 结果，构建 / 测试命令与结果，开工前已有的失败，未验证项如实写）、自审结论；按完整流程第 4 步记录运行反馈；然后只问提交（建议的 commit message）。用户说「落盘交付说明」或之后要出上线方案时，再按下面的完整流程补落盘。
-
-完整流程：
-
-1. **落盘交付说明**：模板路径用 `node <skills>/workflow/scripts/resolve.mjs template dev delivery-template.md` 取（退出码 2 时停下并按 `hint` 处理），写到 `requirement.mjs path delivery` 给出的路径（见 Artifact Location）。元信息行的「对比分支」写当前分支和 `profile.main_branch`，`artifacts.mjs`、project-review、上线方案靠它找到这份交付；有开发方案时「参考产物」写方案路径。小改动每节一两行即可，不适用的节写「无」，但验证结果必须如实。
-2. **自检**：运行 `node <skills>/workflow/scripts/lint-doc.mjs <交付路径> --skill dev --template delivery-template.md`，有「错误」先修正。
-3. **对话里给摘要**：结果、验证（含未验证项）、配置 / SQL 有无、交付文件路径；不必把全文贴进对话。
-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`。只写过程，不写代码和业务名词；报错就提一句，不影响交付。
-5. **询问下一步**，不要自行执行：
-   - 提交：给出建议的 commit message 和要 add 的文件（只含本需求的改动，Step 0 确认无关的不 add；建议把交付说明一起提交，随分支保留），用户同意后再 `git commit`；**不 push**，除非用户明确要求。
-   - PR / MR：用户要提 PR / MR 时，运行 `node <skills>/workflow/scripts/pr-desc.mjs`（缺省当前分支、基线 `profile.main_branch`），它把本分支的交付说明、审查报告、技术方案、上线方案汇总成描述（没有交付说明时退回用提交记录和改动文件），把输出给用户；用 `gh pr create` / `glab mr create` 创建要用户明确同意。
-   - 文档：运行 `node <skills>/workflow/scripts/artifacts.mjs` 看本分支已有哪些产物（开发方案、交付说明、审查报告、技术方案、上线方案及 wiki 发布记录），按输出的 `next` 建议下一步：M / L 规模缺技术方案时建议 `create-tech-md-doc`，要上线时建议 `create-release-md-doc`（会自动引用本分支的技术方案和交付说明）。
-   - **沉淀到 DocNexus**（`resolve.mjs status` 的 `docnexus.ok` 为 true 时**每次都问**）：明确问用户「要不要启动 DocNexus 流程，把本次交付沉淀到 DocNexus？」，并从交付说明里列出建议沉淀的内容（已确认的决定、新约定、踩到的坑、缺陷根因、配置 / 表结构变化）；没有特别值得记的也照问，并说明这一点。
-     - 用户同意 → 以交付说明为来源，按 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>`，并回报给用户。
-     - 用户不同意 → 元信息行保持「未沉淀」，不再追问。
-     - 未接入 DocNexus → 元信息行写「未接入」，不提问、不提示安装。
+读 [delivery.md 的 F8](references/delivery.md)；完整流程取得交付选择后用 `requirement.mjs path delivery` 写 `delivery.md`、自检并汇总，快速通道仅对话交付。反馈用 `feedback.mjs add`；沉淀分类用 `resolve.mjs category dev`，详细授权、元信息与后续操作按该文执行。
 
 ## 缺陷修复流程（`--bug`）
 
 ### B1 — 收集现象
 
-整理：现象、期望行为、触发条件、影响范围、首次出现时间、相关日志 / 报错 / 数据。信息不足以复现时，列出缺的信息问用户：只问只有用户知道的（日志、发生时间、操作步骤、受影响的用户），代码和数据能查到的自己查；格式同 `references/clarify.md`。
+读 [bug.md 的 B1](references/bug.md)；整理现象、预期、触发条件、日志与影响范围，形成复现输入。
 
 ### B2 — 复现
 
-- 优先写一个**能稳定失败的测试**来复现；写不出测试时给出可执行的复现步骤（请求、参数、数据）。
-- 涉及数据问题 → 用 `database-query` 只读查询核对现场数据，敏感字段脱敏。
-- 复现不了 → 停下来说明尝试过什么，不要在没复现的情况下猜着改。
+读 [bug.md 的 B2](references/bug.md)；优先失败测试，否则提供可执行复现步骤；复现不了先说明尝试，不猜着改。
 
 ### B3 — 定位根因
 
-- 沿调用链找到**第一个**出错的位置，用证据（代码行、日志、数据、git 历史 `git log -L` / `git blame`）说明为什么错。
-- 区分根因与症状：只在出错表象处加判空 / try-catch 不算修复，除非能说明那里就是根因。
-- 检查同一根因是否在其他调用方同样存在。
+读 [bug.md 的 B3](references/bug.md)；沿链路找第一个出错位置，以代码 / 日志 / 数据 / 历史形成根因证据，并查同类风险。
 
 ### B4 — 修复与验证
 
-- 修复前按 F4 的标准判定规模，并完成同样的规模确认（S / M / L 都适用，说明是否走快速通道及落盘要求）；用户明确确认后再改代码。修复中规模变化时先确认新规模再继续。
-- 做能消除根因的**最小改动**；B2 的测试由红变绿，相关已有测试保持通过（运行方式同 F6）。
-- 如果历史脏数据需要修正，写成 SQL 脚本交给用户，不直接执行。
-
-### B5 — 自审与交付
+先读 [bug.md 的 B4](references/bug.md) 和 planning.md 的 F4；完整流程通过 `requirement.mjs path plan` 归档旧版后，在原 `plan.md` 追加修复方案并更新文档头，不另建方案；M / L 确认后修复，复现测试由红变绿。
 
-同 F7、F8（交付说明同样落盘，「类型」写缺陷修复）。快速通道同样适用于缺陷修复：S 规模、不涉及配置 / SQL / 对外接口 / 表结构 / 权限 / 资金，且同类风险排查没有发现其他调用方受影响时，在对话里交付，但根因（证据链、修复方式）必须在对话里写清楚。交付说明的「根因」节必须写：证据链、修复方式、为什么这样修、同类风险排查结果；DocNexus 沉淀时根因是首要候选。
+### B5 — 审查与交付
 
-## Rules
-
-- 不执行任何写库操作；不修改 `config.json` / `wiki-config.json` 等凭据文件。
-- 不 `git commit` / `git push` / 改写历史 / 删除分支，除非用户在本次对话中明确要求。
-- 不安装新依赖；确实需要时说明理由，等用户同意。
-- 每个关于现有代码的结论都指向真实文件和行号；读不到的内容如实说明。
-- 用户中途改变需求 → 回到 F3，只就变化的部分重新澄清并更新验收标准，再继续。
+读 [bug.md 的 B5](references/bug.md)，再按 F7 / F8；完整交付记录根因证据、修复方式、理由与同类风险排查，快速通道在对话中给出这些内容。
 
 ## Artifact Location
 
-产物按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`，规则见 `<skills>/workflow/references/requirements.md`：
+正式产物按 `<skills>/workflow/references/requirements.md` 归入 `workflow-run/docs/requirements/<需求>/<项目>/`，首次落盘前 bind；写入与归档细则见 [delivery.md 的 Artifact Location](references/delivery.md)。写完 sync，用输出的 cite 引用，lint 错误先修正。
+普通聊天的辅助文件默认放 `workflow-run/other/`，不绑定需求、不登记运行；源码、已有文件和用户指定路径沿用原规则。
 
-- **需求名**：确定规模为 M / L（要落盘）时，先运行 `node <skills>/workflow/scripts/requirement.mjs which`；当前分支还没绑定需求就问用户这个需求叫什么（默认值用输出的 `suggested_name`），再 `requirement.mjs bind --name "<需求名>"`；用户不给名字时 `bind` 按分支名生成。S 规模快速通道不落盘，不问。缺陷修复同样处理（可以选择挂到原需求下）。
-- **路径**：交付说明用 `requirement.mjs path delivery`，L 规模方案（或用户要求落盘的 M 规模方案）用 `requirement.mjs path plan`，写到输出的 `path`；文件名固定，已有旧版时直接写新版，上一版由脚本归档（输出的 `previous`）。
-- 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`；输出里 `archived` 非空（上一版已归档到 `workflow-run/tmp/old-artifacts/`）时告诉用户归档了哪些文件，请用户确认不再需要后自己删除；输出里 `commit` 非空（独立文档仓库模式）时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物（「参考产物」等）写 `requirement.mjs path` 输出的 `cite`。
-
-## 终端命令
+## Rules
 
-本 skill 给出的 `node …`、`git …` 命令在 bash、zsh、PowerShell 里写法一样，原样运行即可。需要自己写其他终端命令时，先看本机的系统和终端：`node <skills>/workflow/scripts/resolve.mjs env`（安装时记录，一次对话查一次就够；`resolve.mjs profile` / `status` 的输出里也带着 `env`）。按输出的 `os`、`shell`、`note` 写命令，不要再用 `uname`、`$PSVersionTable`、`ver` 之类去探测。
+- 不直接写库、不改凭据文件；SQL 只生成脚本。安装新依赖、提交、推送、改写历史、删除分支须有用户授权。
+- 不改无关代码；现有代码结论引用真实文件和行号，测试没跑不能说通过。
+- 用户改变需求回 F3，只澄清变化部分并更新验收标准。

package/dev/references/bug.md

@@ -0,0 +1,30 @@
+# 缺陷修复
+
+仅在 --bug 模式进入 B1～B5 时读取对应小节；规模与快速通道规则复用 planning.md 的 F4，审查交付复用 delivery.md。
+
+### B1 — 收集现象
+
+整理：现象、期望行为、触发条件、影响范围、首次出现时间、相关日志 / 报错 / 数据。信息不足以复现时，列出缺的信息问用户：只问只有用户知道的（日志、发生时间、操作步骤、受影响的用户），代码和数据能查到的自己查；格式同 `clarify.md`。
+
+### B2 — 复现
+
+- 优先写一个**能稳定失败的测试**来复现；写不出测试时给出可执行的复现步骤（请求、参数、数据）。
+- 涉及数据问题 → 用 `database-query` 只读查询核对现场数据，敏感字段脱敏。
+- 复现不了 → 停下来说明尝试过什么，不要在没复现的情况下猜着改。
+
+### B3 — 定位根因
+
+- 沿调用链找到**第一个**出错的位置，用证据（代码行、日志、数据、git 历史 `git log -L` / `git blame`）说明为什么错。
+- 区分根因与症状：只在出错表象处加判空 / try-catch 不算修复，除非能说明那里就是根因。
+- 检查同一根因是否在其他调用方同样存在。
+
+### B4 — 修复与验证
+
+- 修复前按 F4 的标准判定规模并告知用户（规模不询问确认）；S 规模符合快速通道条件时照 F4 问用户是否走快速通道，问完等本轮答复再改代码：明确同意才走快速通道（不落盘），拒绝或未明确同意按完整流程。
+- **完整流程先把修复方案追加进 `plan.md`**：按 Artifact Location 运行 `requirement.mjs bind`（未绑定时），再用 `requirement.mjs path plan` 拿路径（已有 `plan.md` 时脚本会先把上一版归档到 `workflow-run/tmp/old-artifacts/`），把根因结论与修复方式写成 `plan.md` 的「修复方案」一节**追加**在原文之后（前面留一个空行与上一节隔开，避免标题被上一行吞掉）——保留已有方案正文、不另建文件；同时将文档头的分支更新为当前修复分支、日期更新为本次日期，不能只在追加的章节里写新分支，否则产物索引仍会归到旧分支。没有 `plan.md` 时按模板建一份，只填适用的节。写完 `requirement.mjs sync <方案路径>` 更新 `meta.json`，运行 `node <skills>/workflow/scripts/lint-doc.mjs <方案路径> --skill dev` 自检，再运行 `artifacts.mjs --branch <当前修复分支>` 确认 `latest.plan` 指向这份方案；M / L 等用户确认修复方式后再改代码，S 可以在同一轮确认并开始。修复中规模变化时说明变化依据，按新规模继续。
+- 做能消除根因的**最小改动**；B2 的测试由红变绿，相关已有测试保持通过（运行方式同 F6）。
+- 如果历史脏数据需要修正，写成 SQL 脚本交给用户，不直接执行。
+
+### B5 — 审查与交付
+
+同 F7、F8：优先由独立子 agent 审查（没有子 agent 时在当前会话自查）并落盘 `review.md`，交报告后等待用户选择修复或交付；修复后验证、复审，再等选择，完整流程仅在用户选择交付后生成 `delivery.md`（「类型」写缺陷修复）。快速通道同样适用于缺陷修复：S 规模、用户在 B4 已同意走快速通道，不涉及配置 / SQL / 对外接口 / 表结构 / 权限 / 资金，且同类风险排查没有发现其他调用方受影响时，不绑定需求、不落任何产物文件，审查在当前会话做，交付在对话里一次完成并注明「DocNexus：未询问（快速通道不问沉淀）」；根因（证据链、修复方式）必须在对话里写清楚。完整交付时，交付说明的「根因」节必须写：证据链、修复方式、为什么这样修、同类风险排查结果；DocNexus 沉淀时根因是首要候选。

package/dev/references/delivery-template.md

@@ -2,10 +2,10 @@
 
 > 类型：{{功能开发 / 缺陷修复}} ｜ 规模：{{S / M / L}} ｜ 日期：{{YYYY-MM-DD}}
 > 对比分支：`{{当前分支}}` ←→ `{{主分支}}`
-> 参考产物：{{开发方案路径，没有写「无」}}
-> DocNexus：{{沉淀后写 workflow-run/docnexus/library/<path>；未沉淀写「未沉淀」，未接入写「未接入」}}
+> 参考产物：{{最新审查报告路径（独立子 agent 或当前会话自查）；方案路径（非快速通道都有）}}
+> DocNexus：{{尚未发起询问写「未询问」；沉淀后写 workflow-run/docnexus/library/<path>；没有值得沉淀的内容写「无需沉淀」，已询问但未成功入库（含用户拒绝）写「未沉淀」}}
 
-<!-- F8 / B5 交付时按此落盘到 requirement.mjs path delivery 给出的路径（workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md）。小改动每节写一两行即可，不适用的节写「无」；验证结果必须如实 -->
+<!-- F7 审查报告交给用户且用户明确选择交付后，F8 / B5 才按此落盘到 requirement.mjs path delivery 给出的路径（workflow-run/docs/requirements/<需求名>/<项目名>/delivery.md）。小改动每节写一两行即可，不适用的节写「无」；验证结果必须如实 -->
 
 ## 结果 *
 
@@ -44,13 +44,13 @@
 
 {{文件路径或脚本内容；涉及的表与核对结果：已与 <连接名> 核对（字段 / 索引 / 估算行数）或「未与实际库核对」；无则写「无」}}
 
-## 自审
+## 审查
 
-{{project-review 结论摘要；遗留的 MEDIUM / LOW}}
+{{最新审查报告路径与结论；修复和复审结果；用户选择交付及明确接受的遗留问题 / 风险，不得将带问题交付写成审查通过}}
 
 ## 范围外发现
 
-{{顺带看到但本次未处理的问题；开工前工作区里与本需求无关的改动（文件列表，未提交）及自审在其中发现的问题；无则写「无」}}
+{{顺带看到但本次未处理的问题；开工前工作区里与本需求无关的改动（文件列表，未提交）及审查在其中发现的问题；无则写「无」}}
 
 ## 建议下一步