@rowansenne/workflow-run 0.25.0 → 0.27.0

package/dev/references/delivery.md

@@ -0,0 +1,48 @@
+# 审查与交付
+
+进入 F7 / F8 或缺陷修复 B5 前读取对应小节；首次正式落盘前读取 Artifact Location。
+
+### F7 — 审查、报告与用户选择
+
+**S 快速通道不走本节**：在当前会话按 project-review 的标准清单自查，不写方案、不落 `review.md`、不绑定需求、不交报告等选择；审查结论写进 F8 的对话交付。碰到快速通道的退出条件时，再按下面的完整流程走。
+
+- 按 `project-review` skill 审本次改动，用户未指定深度时按 project-review 的「标准」审查。范围用 `node <skills>/workflow/scripts/review-scope.mjs --base <main_branch>`：分支已有的提交、未提交的改动和未跟踪的新文件一起列出。Step 0 确认不属于本需求的文件用 `--exclude <文件,文件>` 排除，它们不计入本次结论（见 Step 0「工作区状态与工作分支」）；之后 project-review 的 `rules`、`locate.mjs` 都带同样的参数。
+- **优先由独立子 agent 审查**：派一个未参与本轮实现的子 agent，执行 project-review 的第 1～7 步（含复核和落盘报告）。只交接项目根、skills 路径、分支 / 基线、排除范围、审查深度（默认标准）、需求与验收标准、已确认决定、方案路径、验证命令与结果、上次报告路径；不要传实现者的自审结论或预设问题，让它自己读当前代码判断。审查期间主 agent 不再修改被审代码。子 agent 只审查、写审查产物，不修代码、不生成交付说明、不提交。
+- **没有子 agent 时在当前会话审查**：按 project-review 第 1～7 步自己走完并落盘 `review.md`，报告的「审查者」写当前 agent（未派子 agent）；问题表、复核、报告、等用户选择都不省。不要写成独立审查，也不要跳过审查直接进 F8。
+- **每轮必须落盘 `review.md`**：按 Artifact Location 先绑定需求，再按 project-review 第 7 步生成报告、运行 lint 和 sync。问题表、影响面、未覆盖项都要保留；没有发现也生成报告。只跳过 project-review 第 8 步沉淀与第 9 步反馈，沉淀和反馈留给 dev F8 统一处理；报告的元信息固定写「未询问（由 dev 交付统一处理）」。F8 只更新交付说明的沉淀状态，不将内部审查报告同步为交付的沉淀结果，避免把一次询问或沉淀重复计数。本轮尚无交付说明，不能把缺少 `delivery.md` 当成漏项；旧交付说明只能作为历史参考，当前需求与验证以本次交接为准。
+- **先交报告，再等选择**：主 agent 读取报告，将报告内容与路径交给用户，明确询问「修复报告中的问题，还是按当前结果交付？」并等待本轮明确答复。没有发现时也要等用户选择交付；答复含糊或未答复时留在 F7。此时**不创建、不覆盖 `delivery.md`，不提前进入提交、PR 或沉淀环节**。
+  - **修复问题**：按用户选定的问题回到 F5 修复、F6 验证，再由未参与修复的子 agent（没有子 agent 时在当前会话）重新走 F7；复审更新 `review.md`，旧版按产物规则归档，逐条核对「已修复 / 仍存在 / 不再适用」。再次交报告、等待选择，不因已修复就自动交付。用户自己修复后也走 F6 → F7，不能只凭口头说已修复关闭问题。
+  - **交付**：确认报告对应当前代码；审查后代码有变动就先回 F6 → F7。仍有已复核的 CRITICAL / HIGH 时，明确建议先修复，说明具体风险并让用户确认是否仍按当前结果交付；不能将一般的「交付」视为接受未说明的严重风险。用户明确接受遗留风险后才进 F8，如实记录遗留问题与未验证项，不得把带问题交付写成「审查通过」或「建议合并」。MEDIUM / LOW 的处理结果也写进交付说明（快速通道写在对话里）。
+
+### F8 — 交付
+
+**完整流程的进入条件**：F7 的审查报告已完成并交给用户（独立子 agent 或当前会话审查均可），且用户明确选择「交付」。修复后仍需完成验证与复审、重新取得交付选择；此前不创建或更新 `delivery.md`。选择交付不等于授权提交、推送、发布或沉淀。S 快速通道不经过这个条件、也不生成报告，见下面的「快速通道交付」。
+
+独立文档仓库中 F7 的报告提交提示延后到本步：完整流程交付完成后运行 `requirement.mjs pending`，按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」询问；不让审查环节提前询问或执行提交。
+
+**快速通道交付**（见 F4「S 规模快速通道」）：一次对话交付，不绑定需求、不落任何产物文件——方案、`review.md`、交付说明都不写，不跑 lint、不问 DocNexus 沉淀（运行反馈仍照常记一行），交付里注明「DocNexus：未询问（快速通道不问沉淀）」。给：结果一句话、改动文件、验证（验收项 → 测试 / 操作 → 结果，构建 / 测试命令与结果，开工前已有的失败，未验证项如实写）、当前会话审查的结论与遗留问题；按完整流程第 4 步记录运行反馈；然后只问提交（建议的 commit message）。用户说「落盘交付说明」或之后要出上线方案时，先绑定需求，回到 F4 补方案、F7 补审查报告（`review.md`），取得交付选择后，才按下面的完整流程生成交付说明、判断沉淀。
+
+完整流程：
+
+1. **落盘交付说明**：模板路径用 `node <skills>/workflow/scripts/resolve.mjs template dev delivery-template.md` 取，写到 `requirement.mjs path delivery` 给出的路径（见 Artifact Location）。元信息行的「对比分支」写当前分支和 `profile.main_branch`，`artifacts.mjs`、project-review、上线方案靠它找到这份交付；「参考产物」写最新审查报告，有方案（`plan.md`）时也写方案路径。「审查」节记录报告结论、修复与复审结果、用户选择交付及接受的遗留风险。尚未发起沉淀询问时，元信息先写「未询问」，再按第 5 步更新。小改动每节一两行即可，不适用的节写「无」，但验证结果必须如实。
+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**：先判断本次交付有没有**特别值得记录**的内容——已确认的决定、新约定、踩到的坑、缺陷根因、配置 / 表结构变化；标准是「下次做同类需求时，它能不能少踩一次坑或少做一次决定」，分支、产物路径这类工作流信息不算。
+     - 没有 → **不提沉淀**：元信息行写「无需沉淀」，交付摘要里一句话带过（如「只是改了文案，没有值得沉淀的知识」），不追问。
+     - 有 → 明确问用户「要不要启动 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>`，并回报给用户。
+       - 用户不同意 → 交付说明的元信息行改成「未沉淀」，不再追问。
+     - 元信息更新后运行 `requirement.mjs sync <交付路径>`；F7 内部审查报告的「未询问」不随此结论改变。
+
+## Artifact Location
+
+产物按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`，规则见 `<skills>/workflow/references/requirements.md`：
+
+- **需求名**：Step 0 已运行 `requirement.mjs which` 并问定名字。第一次落盘前运行 `requirement.mjs bind --name "<需求名>"`（用户明确同意按分支名生成时不带 `--name`）；S 快速通道不 bind、不落盘。缺陷修复同样处理（可以选择挂到原需求下）。
+- **路径**：交付说明用 `requirement.mjs path delivery`，方案（非快速通道一律落，S / M 写简版）用 `requirement.mjs path plan`，写到输出的 `path`；文件名固定，已有旧版时直接写新版，上一版由脚本归档（输出的 `previous`）。缺陷修复在 B4 把根因与修复方式**追加**到同一个 `plan.md`（不另建文件）。
+- 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`；输出里 `archived` 非空（上一版已归档到 `workflow-run/tmp/old-artifacts/`）时告诉用户归档了哪些文件，请用户确认不再需要后自己删除；输出里 `commit` 非空（独立文档仓库模式）时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物（「参考产物」等）写 `requirement.mjs path` 输出的 `cite`。

package/dev/references/implementation.md

@@ -0,0 +1,19 @@
+# 实现与验证
+
+进入 F5 / F6，或缺陷修复 B4 执行修复与验证前读取对应小节。
+
+### F5 — 实现
+
+- **小步推进**：按逻辑分步实现，一步改完（或改了公共签名、跨了模块）运行 `profile.build`（没有则用对应构建工具的编译命令）确认通过，再进入下一步。不必每改一个文件就编译，代码没变时不重复跑。
+- **改动前看影响面**：要改公共方法、接口签名、DTO 字段时，先 `node <skills>/code-graph/scripts/cg.mjs entry <Class.method>`（按本轮 CodeGraph 通道），把会被波及的入口和调用方纳入本次改动或写进交付说明。
+- **贴合现有代码**：沿用参照实现的写法；不顺手重构、不改无关代码、不升级依赖。看到范围外的问题记进交付说明，不在本次修。
+- **配置**：新增配置项记入配置清单（key、位置、用途、建议默认值、上线前需下发的环境），按 `profile.config_center` 与审查清单的配置维度处理（清单路径用 `node <skills>/workflow/scripts/resolve.mjs template project-review checklist.md` 取，接入 DocNexus 时是团队维护的版本）。
+- **数据库变更**：DDL / 数据修正写成 SQL 脚本放进项目约定的目录（没有约定则放进交付说明），**不在任何环境直接执行**。写之前按 `<skills>/workflow/references/tables.md` 核对实际表结构：要加的列 / 索引是否已存在、新查询条件有没有索引、表有多大（大表 DDL 写进上线注意事项）。
+- **敏感信息**：不硬编码密钥、密码、内网地址；日志不打印敏感字段。
+
+### F6 — 验证
+
+- 按验收标准补充或更新单元测试 / 集成测试，测试放在项目既有测试目录、沿用既有测试框架。
+- **验收项对应到证据**：F1 / F3 的每条验收标准写明靠哪个测试或手动操作验证、结果如何；没有测试也没法操作的标「未验证」并写原因。交付说明「验证」节的表格按这个填，快速通道在对话里列同样的对应。
+- 先跑相关测试（`profile.test_single`，或代码图谱的 `impact` 选出的测试），修到通过；最后跑一次 `profile.test` 全量（之后又改了代码就再跑）。有 `profile.lint` 时一并运行。全量里出现、基线没跑到的失败，先看失败的测试是否碰到本次改动的代码，确认无关的按已有失败记录并写明依据。按本轮 CodeGraph 通道分析相关测试；script 模式取自 `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 节。
+- 如实报告结果：失败就给出失败输出并继续修；环境跑不了（缺依赖、缺中间件）就明确写「未验证」以及用户该如何验证。**不得声称未运行的测试已通过。**

package/dev/references/plan-template.md

@@ -1,9 +1,11 @@
-# 开发方案 — {{需求名}}
+# 方案 — {{需求名}}
 
-> 规模：{{M / L}} ｜ 分支：{{dev分支}} ｜ 日期：{{YYYY-MM-DD}}
+> 规模：{{S / M / L}} ｜ 分支：{{dev分支}} ｜ 日期：{{YYYY-MM-DD}}
 > 需求来源：{{对话 / PRD 链接}} ｜ 参考记忆：{{workflow-run/docnexus/library/... 或「无」}}
 
-<!-- M 规模在对话中给出时，只需要第 1、3、4、6 节，每节几行即可 -->
+<!-- 非快速通道一律落盘：S / M 只需要第 1、3、4、6 节，每节几行即可；L 写完整。走 S 快速通道时不写本文件。
+     缺陷修复在 B4 追加一节「## 修复方案（根因 + 修复方式）」，前面留一个空行与上一节隔开，保留原方案正文；文档头的分支与日期更新为当前修复分支和本次日期，上一版由 path plan 归档。
+     标题里的「方案」同时覆盖功能开发与缺陷修复两种用法。 -->
 
 ## 1. 需求要点与验收标准
 

package/dev/references/planning.md

@@ -0,0 +1,45 @@
+# 需求调研与方案
+
+功能开发进入 F1～F4 时读取对应小节；缺陷修复在 B4 判定规模与快速通道前读取 F4。
+
+### F1 — 理解需求
+
+- 需求来源是 PRD pageId/URL → 按 `prd-fetch.md` 拉取并提炼。
+- 先运行 `node <skills>/workflow/scripts/knowledge.mjs dev --match <模块名 / 业务名词> --query "<一句话需求>"`，看以往开发沉淀、技术方案和反复出现的审查问题里有没有相关的（`--query` 在这些分类内按正文 recall）。引用 `workflow-run/docnexus/library/<path>`（见 `<skills>/workflow/references/docnexus.md`「按分类参考知识库」）。
+- 先在心里列出初版 **需求要点 + 验收标准**（可验证的行为，而不是实现手段）和还没定的决定，带进 F2 查事实、F3 澄清。
+
+### F2 — 现状调研
+
+- 从入口（Controller / Handler / CLI / 页面）沿调用链读到持久层，理清数据流；不凭文件名猜内容。按本轮 CodeGraph 通道先用 `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 以查到的为准，不凭实体类推测。
+
+### F3 — 需求澄清
+
+按 `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 的业务决定，不影响 S 规模快速通道资格。
+
+**落盘前绑定需求名**：Step 0 已经问定需求名；确定不走快速通道、第一次要落盘时，按 Artifact Location 运行 `requirement.mjs bind`（已绑定则跳过），之后的方案、审查、交付、技术方案、上线方案都归到这个需求下。S 快速通道不绑定。
+
+**S 规模快速通道（问用户）**：判定为 S 规模，且改动**不涉及**配置项、SQL / DDL、对外接口（HTTP 接口签名、MQ 消息体、对外 DTO）、表结构、权限、资金，也没有 F3 中确认过的业务决定时，**明确询问用户是否走快速通道**：说明走快速通道时 F5～F6 照常（编译、测试都不省），审查按 F7 的快速通道说明在当前会话做，但**不绑定需求、不落任何产物文件**——方案、`review.md`、交付说明都不写（运行反馈仍照常记一行），F8 在对话里一次交付并注明 DocNexus「未询问」。**问完等本轮答复再继续：明确同意才走快速通道；拒绝或答复没有明确同意，就按完整流程落盘交付（F4 方案 → F7 审查 → F8 交付）。** 实现中一旦碰到上面任何一项、改动超过 3 个文件，或用户要求落盘 → 退出快速通道：先停下后续实现，重新评估并说明规模，按 Artifact Location 绑定需求，回到 F4 补写 `plan.md` 并自检（缺陷修复按 B4 追加修复方案）；M / L 等用户确认方案后再继续，S 按简版方案推进。之后回 F5 完成实现、F6 验证、F7 审查并生成 `review.md`，交报告后等待用户选择交付，不从绑定直接跳到审查或交付。快速通道只省落盘与沉淀询问，不省审查。
+
+**方案一律落盘（走快速通道除外）**：S / M / L 都写方案文档，规模只决定详细程度和确认方式。方案模板：在项目根运行 `node <skills>/workflow/scripts/resolve.mjs template dev plan-template.md`，读输出的 `path`。方案落盘后运行 `node <skills>/workflow/scripts/lint-doc.mjs <方案路径> --skill dev` 自检；M / L 等用户确认后再写代码，S 可以在同一轮确认并开始（方案按简版写）。S 先按上面的快速通道问一次：同意则不写方案，不同意或未明确同意才落盘。

package/dev/references/preflight.md

@@ -0,0 +1,35 @@
+# 开工与运行状态
+
+进入 Step 0 或恢复运行前读取；只读当前事项对应小节。完整状态协议复用 `<skills>/workflow/references/runs.md`。
+
+## 完整流程的运行状态
+
+按 `<skills>/workflow/references/runs.md` 保存和恢复进度，状态统一在需求的 `meta.json`，不另建状态文件。确定工作分支后先 `run.mjs show`；用户要求继续时读取对应运行的 context、已完成步骤与等待事项，核对代码和证据后从保存的阶段恢复，不重走有效的已完成步骤。不能把“继续”当成用户选择交付。
+
+新任务确定不走快速通道后，先绑定需求，再 `run.mjs start --kind feature|bug --size <规模> --input <checkpoint.json>`，把前置步骤、验收标准、已确认决定、范围、基线与待办补入第一份 checkpoint。功能开发在 F4 创建（Step0、F1～F3 按真实进度补记），缺陷修复在 B4 创建（Step0、B1～B3 补记）；快速通道不 start、不 save。
+
+每个步骤完成、等待用户、遇到阻塞和结束本轮会话前 save，明确标记步骤 completed 并记录证据。方案待确认时运行为 waiting_user；F7 报告交给用户后也保存 waiting_user 和“修复或交付”，不能仅因报告存在就继续。用户选修复时记录确认的 fix 并回 F5（bug 回 B4），自动重置后续完成标记；选交付时记录确认的 deliver 并进 F8（bug 留 B5）。规模变化同时更新 size。
+
+完整交付说明、自检、摘要和反馈完成后，将 F8（bug 为 B5）标 completed，再执行 `run.mjs complete`，保存运行的 **completed（已完成）与 completed_at**；可选后续动作不阻塞本次已完成的交付，也不自动获得执行授权。已完成运行不再覆盖，新工作使用新的运行记录。dev 内部的审查子 agent 只返回报告和证据，由主 agent 更新同一运行，不能另起 review 运行或并发覆盖状态。
+
+## 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/requirement.mjs which`。
+   - 后续新建或切换分支时，重新运行 `requirement.mjs which`；不要沿用旧分支的 `bound` 结果或自动读到的需求名。用户明确确认继续同一需求时，才将该名字用于新分支。
+   - 当前工作分支已绑定 → 直接用，不再问。
+   - 本次对话里用户（或 `/workflow` 入口）已经给过名字、只是还没绑定 → 直接用这个名字，不再问。
+   - 没绑定 → **现在就问用户这个需求叫什么**（默认值用输出的 `suggested_name`；用户说「按分支名」也行）。**用户给不出名字、或说不清这次要做什么时停在这里，不进入 F1**，已开始的改动保持原样，不替用户猜。名字在第一次落盘时按 Artifact Location bind；S 快速通道只问不 bind、不落盘。
+4. **审查方式**：确认当前环境能否派独立子 agent（`resolve.mjs status` 探测不到这个能力）。能派 → F7 用独立子 agent；不能派 → F7 在当前会话按 project-review 自查，报告「审查者」写当前 agent，不阻塞流程。
+5. **基线**：动代码前运行一次 `profile.build`，再跑和本需求相关的测试（`profile.test_single` 或相关模块，不必全量），记下已经失败的测试和编译错误。之后只对新增的失败负责：已有失败不顺手修，写进交付说明「开工前已有的失败」。跑不了就记「未跑基线」和原因。
+
+## 终端命令
+
+本 skill 给出的 `node …`、`git …` 命令在 bash、zsh、PowerShell 里写法一样，原样运行即可。需要自己写其他终端命令时，先看本机的系统和终端：`node <skills>/workflow/scripts/resolve.mjs env`（安装时记录，一次对话查一次就够；`resolve.mjs profile` / `status` 的输出里也带着 `env`）。按输出的 `os`、`shell`、`note` 写命令，不要再用 `uname`、`$PSVersionTable`、`ver` 之类去探测。

package/dev/skill.json

@@ -16,8 +16,8 @@
     {
       "id": "plan-template.md",
       "src": "references/plan-template.md",
-      "title": "开发方案模板",
-      "summary": "dev skill 在 M / L 规模需求中使用的开发方案模板。",
+      "title": "方案模板（开发 / 修复）",
+      "summary": "dev skill 在非快速通道（S / M / L）落盘方案时使用；缺陷修复在 B4 追加「修复方案」节。",
       "lint": {}
     },
     {

package/md-to-wiki/SKILL.md.tpl

@@ -5,6 +5,8 @@ description: "Publish a local Markdown document to an existing Confluence wiki p
 
 # MD to Wiki
 
+**开工能力**：先运行 `node <skills>/workflow/scripts/resolve.mjs status`，按 `<skills>/workflow/references/capabilities.md` 选择本轮能力与模板；同一项目链路复用已有快照，失败统一按该规则处理。
+
 把本地 Markdown 转成 Confluence Storage Format（严格 XHTML），校验后写入**已有**的 wiki 页面。
 
 ## GATE — 未配置则禁止启动（最高优先级）
@@ -39,10 +41,12 @@ description: "Publish a local Markdown document to an existing Confluence wiki p
 1. GATE 通过。
 2. `<mdPath>` 存在。
 3. 确定目标页面：用户给了 pageId / URL 就解析它（提取不出 → 请用户重新提供，**不要猜**）；没给就运行 `node <skillDir>/scripts/upload.mjs target <mdPath>` 读文档第一行的发布记录（`<!-- md-to-wiki: pageId=... -->`，转换时会被丢弃，不会出现在页面上）。有记录就用它，并在 Step 2 的确认里注明「沿用上次发布的页面」；没有记录 → 请用户提供 pageId，停。用户给的 pageId 与记录不同时以用户给的为准，并提醒。
-4. 选择上传通道：环境有 wiki MCP 工具 → 通道 A；否则用 `wiki-config.json` 的 REST 参数 → 通道 B；都不可用 → 停。
+4. 按本轮 `wiki.channel` 选择上传通道：mcp 为 A，rest 为 B。发布的前置门槛按共享能力规则处理。
 5. 读取目标页面当前的标题、版本号：通道 A 用 MCP 的 `get_page`，通道 B 用 `node <skillDir>/scripts/upload.mjs info <pageId|url>`（细节见 `references/upload.md`）。页面不存在或无权限 → 停。
 6. 本机有 Node.js（≥ 18）；转换脚本不依赖任何第三方库。
 
+**需求文档的运行状态**：workflow 已安装且发布的是已绑定需求的产物时，先从 Markdown 所在需求目录的 meta.json 及文档头确定其归属需求与分支，按 `<skills>/workflow/references/runs.md` 创建／恢复 kind `wiki` 运行，start 显式传 `--dir <来源需求目录> --branch <文档归属分支>`，后续 show / save / complete 都传同一分支和运行 id，不按当前 checkout 猜归属；分支缺失或有歧义时先确认，不能把发布记录写进当前 checkout 的其他需求。W0～W2 对应 Step 0～2；记录文档路径、目标页面和版本，上传确认前保存 waiting_user。成功验证版本递增、回写发布记录后，将 W2 标 completed 并 complete；不能在转换通过或只取得上传授权时就标记完成。`--validate-only` 只校验、不创建发布运行。workflow 未安装或单独发布其他 Markdown 时，不为记录状态强制绑定需求。
+
 ### Step 1 — 转换并校验
 
 ```bash

package/md-to-wiki/skill.json

@@ -1,10 +1,10 @@
 {
   "name": "md-to-wiki",
   "order": 5,
-  "requires": [],
-  "optional": [
+  "requires": [
     "workflow"
   ],
+  "optional": [],
   "userFiles": {
     "wiki-config.json": "wiki-config.json.tpl"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowansenne/workflow-run",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "项目级 Agent Skills 一键初始化：workflow / dev / project-review / code-graph / database-query / md-to-wiki / 技术与上线方案生成",
   "keywords": [
     "agent-skills",
@@ -15,7 +15,7 @@
   "type": "module",
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13"
   },
   "bin": {
     "workflow-run": "bin/workflow-run.mjs"

package/project-review/SKILL.md.tpl

@@ -5,92 +5,66 @@ description: "Review source code (any language; Java/Spring, Go, TypeScript, Pyt
 
 # Code Review
 
+审代码并输出有证据的发现；用户未要求修复时不改业务代码。进入每步前读取所指 reference 的对应小节，不预先加载全部方法说明。
+
+## 门禁
+
+- 开工运行 `node <skills>/workflow/scripts/resolve.mjs status`，按 `<skills>/workflow/references/capabilities.md` 复用本轮能力快照；DocNexus 必装，不可用先修复。
+- 审查范围以 `review-scope.mjs` 输出为准；只报本次引入的问题，范围外发现单列，不把没覆盖写成没问题。
+- 每条结论引用真实代码与文件行号，行号由 `locate.mjs` 定位；CRITICAL / HIGH 必须复核，有条件时交独立 agent。
+- dev 完整流程调用：执行第 1～7 步，零发现也落盘；只返回报告与证据，不修代码、不生成 delivery.md、不提交、不另开 review 运行，跳过第 8～9 步。
+- dev 内部报告写「未询问（由 dev 交付统一处理）」，缺本轮 delivery.md 是正常时序；主 agent 交报告后等用户选修复或交付。S 快速通道仅当前会话审查。
+- 深审大改动的分角度并行查找须用户同意；写入知识库与其他对外动作仍须授权。
+
+## 运行状态
+
+独立正式报告开工前读 [reporting.md 的运行状态](references/reporting.md)：绑定目标需求与分支，用 `run.mjs show` 恢复，必要时 `run.mjs start --kind review` 创建运行，R1～R7 对应第 1～7 步。
+每步完成、等待或受阻时 save；报告落盘、自检并交用户后，R7 标 completed，再 complete 保存已完成和完成时间。
+灵活模式不建运行；dev 内部由主 agent 更新 F7 / B5。状态协议见 `<skills>/workflow/references/runs.md`。
+
 ## Workflow
 
-1. **确定审查范围与深度**：范围是单文件 / 单方法、分支对比（如 `branch` vs `main`），还是未提交改动（见 `references/diff-strategy.md`「未提交改动」）。分支对比和未提交改动都先运行 `node <skills>/workflow/scripts/review-scope.mjs --diff <基线>...<dev>`（未提交改动用 `--base <基线>`，含未跟踪的新文件；dev 自审时加 dev 传来的 `--exclude`），**审哪些文件以它的 `review` 为准**：`skipped` 是按规则跳过的（删除、二进制、敏感文件、依赖目录、生成文件、文档、本工具的产物，各带原因），不要自己再增减；确实要审被跳过的，在画像 `review.include` 里加（见 `<skills>/workflow/references/profile.md`）。深度按用户的说法定，没说就用「标准」，写进报告「审查方式」：
-   - **快审**（「快速看一下」「扫一眼」）：只查正确性、空值、安全、事务与幂等，不查性能、测试、风格；「优化建议（LOW）」写「无」。CRITICAL / HIGH 照样复核。
-   - **标准**（默认）：检查清单全部维度，**风格类（清单「一致性 / 风格」一节）不查**；「优化建议（LOW）」只写有实际收益的（性能、可维护性上的具体问题），没有就写「无」。
-   - **深审**（「仔细审」「全面审」，或资金 / 权限 / 对外接口的大改动合并前）：全部维度，包括风格；MEDIUM 也复核。
-2. **建立理解**：先读实体、接口、DTO、调用链，理清数据流再下结论；不要凭文件名猜内容。
-   - **可选：查项目约定（DocNexus）**：DocNexus 可用时（`resolve.mjs status` 的 `docnexus.ok`），先运行 `node <skills>/workflow/scripts/knowledge.mjs project-review --match <模块名 / 业务名词> --query "<一句话：改动涉及的模块与业务>"`，看以往审查沉淀的反复问题和开发约定（`--query` 在这些分类内按正文 recall），找相关的编码约定、历史决策与已知坑，作为审查依据并在报告中引用 `workflow-run/docnexus/library/<path>`。未检测到或查询失败就跳过，并在「未覆盖与待确认」中注明；审查过程中**不写入** DocNexus（写入见第 8 步）。
-   - **同分支已有产物**：运行 `node <skills>/workflow/scripts/artifacts.mjs --branch <dev分支>`（单文件 / 未提交改动用当前分支，省略 `--branch`），看输出的 `latest`：
-     - `latest.plan` 或 `latest.tech` 存在 → 读其中的验收标准、改动设计、接口 / 数据 / 配置变更，第 3 步审 diff 时做**需求对照**：方案里有、diff 里找不到的 → 漏实现（属于验收标准的按 HIGH，其余 MEDIUM）；diff 里有、方案里没提的接口 / 表结构 / 配置 / 依赖变更 → 列出请作者确认（不一定是问题）。只对照能在 diff 里核对的项，不推测业务语义。
-     - `latest.delivery` 存在（dev 的交付说明）→ 其中「已确认的决定」并入需求对照的依据；「配置清单」「SQL 脚本」和 diff 对照，diff 里有而交付说明漏列的配置 key / DDL 记为 MEDIUM（上线时会被漏掉）。
-     - `latest.review` 存在 → 这是**复审**：读上次报告的问题表，并用 `git log --oneline --since=<上次报告日期> <dev分支>` 看之后改了什么。本次报告对上次的每条问题标「已修复 / 仍存在 / 不再适用」（「已修复」要看到对应改动），本次新发现的标「新增」。
-   - **涉及数据库**：diff 里有 SQL、Mapper、实体或 DDL 时，按 `<skills>/workflow/references/tables.md` 运行 `node <skills>/workflow/scripts/tables.mjs --diff <基线>...<dev>`（未提交改动用 `--base <基线>`）找出涉及的表；数据库已配置（`resolve.mjs status` 的 `database.ok`）时用 `query.mjs --schema --tables <表> --indexes` 只读拉取实际字段、索引与估算行数，作为第 4、6 步判断索引支撑、字段存在与类型、DDL 锁表与滚动发布兼容的依据。查不了库时注明「未与实际库核对」写进「未覆盖与待确认」，这类发现不升到 HIGH 以上，除非 diff 本身就能证明。
-3. **分支对比**：基线默认取 `workflow/profile.json` 的 `main_branch`（未配置则 `main`）。规模和分批用第 1 步 `review-scope.mjs` 的输出：`summary.size` 是「全量精读」就一次读完；「分批精读」按 `batches` 的顺序（P0 → P1 → P2）读，P0 不能跳过；「过大」时停下请用户缩小范围。审不到的文件写进报告（读法见 `references/diff-strategy.md`）。**深审且改动属于「更大」、环境又能派子 agent 时，先问用户要不要分角度并行查找**（`references/diff-strategy.md`「分角度并行查找」），用户同意才走，第 4 步改由各子 agent 按角度过清单。只审本次改动引入的问题，同时检查改动是否破坏既有调用方。
-4. **逐项过检查清单**：每个文件只看 `review-scope.mjs` 给它的 `sections`（清单小节号，按文件类型和改动内容定），一批文件用 `node <skills>/workflow/scripts/review-scope.mjs rules <文件…>`（带上和第 1 步一样的 `--diff` / `--base`）打印这些小节的原文和画像 `review.rules` 里匹配到的项目规则，按它检查；整个改动再过一次 `overall_sections`（9 影响面、13 测试）。深审读整份清单（`node <skills>/workflow/scripts/resolve.mjs template project-review checklist.md` 取 `path`；退出码 2 时停下并按 `hint` 处理），包括风格。对每个发现给出 文件、**问题所在的原代码片段**（从文件里照原样复制，第 6 步靠它定位行号）、问题描述、严重级别、修改建议。
-5. **影响面分析**：改动是否影响其他调用方/模块。先运行 `node <skills>/code-graph/scripts/cg.mjs impact --diff <基线>...<dev>`（code-graph skill；未提交改动用 `--base <基线>`）：列出受影响的接口、MQ 消费者、定时任务、测试、表和配置 key，报告「影响面」按入口归纳并带文件:行号；退出码 2（没有索引等）时用 grep 或精读调用链确认。Spring 注入、AOP、MyBatis XML、MQ topic、配置 key 图谱看不到，照常 grep（见 `<skills>/workflow/references/codegraph.md`）。查不到调用方的符号不能当作安全，要明说"未确认"。
-6. **复核**：交付前逐条复核 CRITICAL / HIGH（深审时 MEDIUM 也复核；其余 MEDIUM 至少做下面第 1 条）。审查结论会被用来决定能不能合并，一条误报会让人白改代码，也会让后面的真问题不被当回事。找出问题的人自己复核容易顺着原来的思路认同自己，所以**能交给独立的一方就交出去**：
-   - **独立复核（首选）**：当前环境能派子 agent / 子任务时（例如 Claude Code 的 Agent 工具、Codex / Qwen Code 的子 agent），每条发现派一个，互不相关的可以同时派。只给它：一句话结论、位置（文件:行号）、你写的触发条件、对比分支（或「未提交改动」）。**不给你的推理过程**，也不告诉它你认为成立。要它自己读代码，按下面 1～4 条检查，回答「成立 / 可能成立 / 不成立」并引用代码作为依据。
-   - **自行复核**：环境派不了子 agent 时自己做，先找它**不成立**的理由，找不到再确认成立。
-   检查项（独立复核和自行复核都按这 4 条）：
-   1. **定位**：把所有发现（包括 MEDIUM / LOW）写成 `workflow-run/tmp/review/findings.json`（数组，每条 `{ "file", "code"（原代码片段）, "line"（你估的行号，可选）, "title" }`），运行 `node <skills>/workflow/scripts/locate.mjs workflow-run/tmp/review/findings.json`（带上和第 1 步一样的 `--diff` / `--base`）。报告里的行号一律用它输出的 `start_line`～`end_line`，不用自己数的。`anchored: false` 的回去重读代码、照原样改片段再跑一次，还找不到就降为 MEDIUM 并标「⚠ 待确认」；`ambiguous` 时看 `candidates` 确认是哪一处；`in_change: false` 说明问题不在本次改动的行上，按第 4 条判断是不是本次引入的。
-   2. 写出**触发条件**：什么输入 / 状态下会出错、错成什么样。写不出来 → 降为 MEDIUM 并标「⚠ 待确认」。
-   3. 找有没有别处已经兜住：调用方校验、`@Validated` / 全局异常处理、数据库约束、框架默认行为、配置。涉及索引、字段、唯一约束、表大小的发现，以第 2 步拉到的实际表结构为准（复核列写「已与 <连接名> 核对」）。已兜住 → 删掉或降级，并在说明里写依据。
-   4. 确认是本次改动引入的：改动前就存在的问题移到「未覆盖与待确认」，不计入合并结论。
-   结果：「成立」在报告「复核」列标「✅」；「可能成立」标「⚠」；「不成立」从问题表里删掉（独立复核否掉的，在「未覆盖与待确认」里记一句「复核排除 N 条」）。复核方式（独立 / 自行）写进报告「审查方式」元信息。
-7. **输出报告**（由 dev 自审调用时跳过第 7～9 步，问题表、影响面、未覆盖项交回 dev 统一交付，见 dev 的 F7）：按报告模板输出（`node <skills>/workflow/scripts/resolve.mjs template project-review report.md` 取 `path`；退出码 2 时停下并按 `hint` 处理），落盘规则见 Artifact Location。
-8. **沉淀到 DocNexus（需用户授权）**：`resolve.mjs status` 的 `docnexus.ok` 为 true 时，交付报告后**每次都问**用户「要不要启动 DocNexus 流程，把本次审查沉淀到 DocNexus？」，并从本次发现里列出建议沉淀的内容：同类问题再次出现（知识库里已有类似沉淀，或本次多处出现）、新确立的编码约定、容易踩的坑；没有特别值得记的也照问，并说明这一点。未接入时不提问，报告的「DocNexus」元信息行写「未接入」。
-   - 用户同意 → 按 DocNexus 入口 skill `docnexus` 的 capture 流程写入；正文只写知识，不写分支、路径；有 facts 时按 `<skills>/workflow/references/docnexus.md`「沉淀的来源」的格式写 provenance；分类用 `node <skills>/workflow/scripts/resolve.mjs category project-review` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」）。只沉淀问题模式和约定，不沉淀某次审查的逐条清单，也不沉淀「⚠ 待确认」的发现；知识库已有同类沉淀时更新那一篇（带 `--base-version`），不要重复新建。写入成功后把报告的「DocNexus」元信息行改成 `workflow-run/docnexus/library/<path>`（多篇用「、」分隔），并回报给用户。
-   - 用户不同意 → 元信息行保持「未沉淀」。
-9. **记录运行反馈**（不问用户）：按 `<skills>/workflow/references/feedback.md` 运行 `node <skills>/workflow/scripts/feedback.mjs add --skill project-review --model <模型名> --mode review --depth <快审|标准|深审> --rounds <提问轮数> --corrections <用户纠正审查范围的次数> --findings <C>/<H>/<M>/<L>`，有跳过的步骤、不清楚或做不到的规则、用户的抱怨时再加 `--skipped` / `--unclear` / `--feedback`。只写过程，不写代码和业务名词；报错就提一句，不影响交付。
+下文 workflow 脚本用 `node <skills>/workflow/scripts/<脚本>` 在项目根执行，终端写法沿用能力快照 env。
+
+1. **确定审查范围与深度**：先读 [review-method.md 的第 1 步](references/review-method.md)。运行 `review-scope.mjs --diff <基线>...<dev>`，工作区用 `--base <基线>`；保留 exclude。默认标准深度，范围与深度写入报告。
+
+2. **建立理解**：读 [review-method.md 的第 2 步](references/review-method.md)。运行 `knowledge.mjs project-review --match <模块> --query "<改动>"`，结合代码、已有产物与实际表结构，形成审查依据和需求对照。
+
+3. **分支对比**：读 [diff-strategy.md](references/diff-strategy.md) 与 review-method.md 第 3 步；按 scope 的 batches 从 P0 到 P2 精读，保留每批发现与未覆盖文件。过大无法过滤时请用户缩小范围。
+
+4. **逐项过检查清单**：读 [review-method.md 的第 4 步](references/review-method.md)。运行 `review-scope.mjs rules <文件…>`，带相同 base / diff / exclude；按匹配小节和 overall_sections 检查，形成附原代码片段的发现。
+
+5. **影响面分析**：读 [review-method.md 的第 5 步](references/review-method.md)。按本轮 CodeGraph 通道分析入口、调用方、测试、表和配置；结果进入报告影响面，找不到调用方明确写未确认。
+
+6. **复核**：必须先读 [verification.md](references/verification.md)。运行 `locate.mjs workflow-run/tmp/review/findings.json`，带相同范围；验证触发条件、防护与引入时间，排除误报，保留成立或待确认的证据。
+
+7. **输出报告**：先读 [reporting.md 的第 7 步与 Artifact Location](references/reporting.md)。用 `resolve.mjs template project-review report.md` 取模板；正式报告落 review.md，sync、lint 后完整交给用户，灵活模式在对话给 findings。
+
+8. **沉淀到 DocNexus**：独立审查交报告后读 [reporting.md 的第 8 步](references/reporting.md)。有值得记录的才询问授权，分类用 `resolve.mjs category project-review`；沉淀结果写报告元信息并 sync。dev 内部不执行。
+
+9. **记录运行反馈**：读 [reporting.md 的第 9 步](references/reporting.md)，用 `feedback.mjs add --skill project-review` 记录过程；不写业务内容，失败不阻塞交付。dev 内部交主 agent 统一记录。
 
 ## 只报会出问题的
 
-报告越短，真问题越不会被漏看。下面这些不报：
-- 风格、命名、格式、注释措辞（快审和标准审查都不报；深审或用户要求时才看）；
-- 编译器、linter、CI 已经会拦下的（未使用的变量、格式、import 顺序）；
-- 个人偏好、没有违反项目约定（`workflow/profile.json` 的 `notes`、DocNexus 约定、审查清单）的写法差异；
-- 写不出后果的「可以更好」：每条发现都要说清不改会怎样。
-
-## Review Dimensions
-
-- 正确性 / 逻辑 bug
-- 字段完整性（实体拷贝是否漏字段、新旧对象赋值是否遗漏、DTO↔实体映射是否缺值）
-- 空指针 / 空值安全
-- 并发与线程安全
-- 异常处理与资源释放（连接、流、锁、事务）
-- 安全（注入 / XSS / 越权 / 敏感信息 / 硬编码密钥）
-- 性能（N+1、循环内查询、大对象、无谓复制）
-- 一致性 / 命名 / 风格（只在深审或用户要求时）
-- 幂等与消息一致性（重复消费 / 回调、事务内发消息）
-- 数据库变更安全（锁表、滚动发布兼容、索引支撑；以实际表结构为准，见第 2 步「涉及数据库」）
-- 测试（改动有没有被测试覆盖、断言是否有效）
-- 语言专项（Java / Go / TS / Python / SQL 各自的常见坑，按改动涉及的语言选读）
-- 配置（见第 4 步取到的审查清单中的配置维度；项目使用的配置中心取自 `workflow/profile.json` 的 `config_center`——配置相关发现按配置清单输出）
+每条发现写清“不改会怎样”。快审 / 标准不报风格，深审或用户要求时才查；不报个人偏好、无实际后果的建议或编译器 / linter 已拦下的问题。详细审查维度见 review-method.md，清单由 rules 命令给出。
 
 ## Severity Levels
 
-- **CRITICAL**：崩溃 / 数据错误 / 资金影响 / 安全漏洞，必须改
-- **HIGH**：明显 bug，特定场景可触发
-- **MEDIUM**：潜在问题，边界未处理或语义存疑
-- **LOW**：有实际收益的优化建议（性能、可维护性）；风格类只在深审时报
+- CRITICAL：崩溃、数据错误、资金影响或安全漏洞；HIGH：有明确触发条件的 bug。
+- MEDIUM：边界或语义存疑；LOW：有实际收益的优化，风格只在深审报。
+- CRITICAL / HIGH 未修不能建议合并；dev 明确接受风险可带问题交付，结论仍保留不建议合并，不等于允许上线。
+- 复核不了的标「⚠ 待确认」，不计入阻止合并的结论；深审还须复核 MEDIUM。具体判定读 verification.md。
 
 ## Output Template
 
-报告结构以第 7 步取到的报告模板为准：元信息（审查范围、对比分支、审查方式、参考产物、DocNexus）、结论摘要、与上次审查对比（复审时）、严重问题（带触发条件与复核列）、一般问题、优化建议、需求对照（有方案时）、配置清单（如有）、影响面、未覆盖与待确认。某一节没有内容写「无」，不要删标题。
-
-> 灵活模式：单文件 / 小改动只在对话里回复时，可以直接列 findings，不必套完整模板；但每个结论必须指向真实文件+行号并引用代码，不得用"应该/大概"下结论，CRITICAL / HIGH 仍要复核。落盘的报告一律用模板。
+正式报告使用知识库模板，空节写「无」不删标题，复审逐项对照上次报告；细则见 reporting.md。
+单文件 / 小改动可用灵活模式只在对话列 findings，但证据与严重问题复核不省；dev 完整流程不能用此模式免落盘。
 
 ## Artifact Location
 
-审查报告按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`，规则见 `<skills>/workflow/references/requirements.md`：
-
-- 路径用 `node <skills>/workflow/scripts/requirement.mjs path review`（分支对比按 dev 分支加 `--branch <dev分支>`），写到输出的 `path`（文件名固定为 `review.md`）；已有报告时脚本先把它归档，输出的 `previous` 是上次报告，复审对照它。
-- 退出码 2（这个分支还没绑定需求）：问用户这个需求叫什么，默认值用输出的 `suggested_name`，再 `requirement.mjs bind --name "<需求名>" [--branch <dev分支>]`；用户不给名字时 `bind` 按分支名生成。
-- 报告同时完整输出到对话；落盘文件与对话内容一致
-- 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`；输出里 `archived` 非空（上一版已归档到 `workflow-run/tmp/old-artifacts/`）时告诉用户归档了哪些文件，请用户确认不再需要后自己删除；输出里 `commit` 非空（独立文档仓库模式）时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物（「参考产物」等）写 `requirement.mjs path` 输出的 `cite`
-- 写完运行 `node <skills>/workflow/scripts/lint-doc.mjs <报告路径> --skill project-review --facts` 自检：「错误」（缺必填章节、缺元信息行、残留 `{{...}}`）先修正；「在 diff 和代码里都找不到」的名字逐个核实，写错了就改成真实的名字
+正式报告按 `<skills>/workflow/references/requirements.md`，用 `requirement.mjs path review [--branch <目标分支>]` 获取路径、归档旧版；写完 sync，并运行 `lint-doc.mjs <路径> --skill project-review --facts`，错误修正后交付。具体执行读 reporting.md。
+普通聊天的分析与草稿默认在 `workflow-run/other/`，不 bind、不建运行、不写需求 meta.json；用户明确路径优先。
 
 ## Verification
 
-- 每个结论都要能定位到具体文件+行号，并引用真实代码片段；行号来自 `locate.mjs`。
-- 读不到的内容如实说明，不要臆测。
-- 涉及跨分支对比时，确保 diff 基于正确的 base 分支（默认 `main`）。
-- CRITICAL / HIGH 都经过第 6 步复核（能派子 agent 时独立复核），写得出触发条件；复核不了的标「⚠ 待确认」，不计入「不建议合并」的结论。
-- `review-scope.mjs` 的每个文件都有交代：`review` 里的都审过，没精读的逐个列在「未覆盖与待确认」；`skipped` 按原因汇总写进同一节（例如「跳过 12 个：生成文件 8、文档 3、敏感文件 1」，敏感文件单独点名提醒）。
-
-## 终端命令
-
-本 skill 给出的 `node …`、`git …` 命令在 bash、zsh、PowerShell 里写法一样，原样运行即可。需要自己写其他终端命令时，先看本机的系统和终端：`node <skills>/workflow/scripts/resolve.mjs env`（安装时记录，一次对话查一次就够；`resolve.mjs profile` / `status` 的输出里也带着 `env`）。按输出的 `os`、`shell`、`note` 写命令，不要再用 `uname`、`$PSVersionTable`、`ver` 之类去探测。
+报告前按 verification.md 核对：真实位置与触发条件、正确基线、复核结果、scope 中每个文件的覆盖情况；读不到、没审到的如实写入「未覆盖与待确认」。

package/project-review/references/report.md.tpl

@@ -2,9 +2,9 @@
 
 > 审查范围：{{分支对比 / 单文件 / 未提交改动}}：{{范围说明}} ｜ 日期：{{YYYY-MM-DD}}
 > 对比分支：`{{dev分支}}` ←→ `{{基线分支}}`（单文件 / 未提交改动两边都写当前分支）
-> 审查方式：{{快审 / 标准 / 深审}}，{{全量精读 / 分批精读（N 批，按风险排序）/ 分 K 个角度并行查找 / 部分摘要化}}，{{独立复核 / 自行复核}} ｜ 清单来源：{{DocNexus / 项目文件 / skill 默认}}
-> 参考产物：{{本分支的开发方案 / 交付说明 / 技术方案路径；复审时加「上次审查 v<N>（<日期>）」；没有写「无」}}
-> DocNexus：{{沉淀后写 workflow-run/docnexus/library/<path>；未沉淀写「未沉淀」，未接入写「未接入」}}
+> 审查方式：{{快审 / 标准 / 深审}}，{{全量精读 / 分批精读（N 批，按风险排序）/ 分 K 个角度并行查找 / 部分摘要化}}，{{独立复核 / 自行复核}} ｜ 审查者：{{独立子 agent / 当前 agent}} ｜ 清单来源：{{DocNexus / 项目文件 / skill 默认}}
+> 参考产物：{{本分支的方案（plan.md）/ 技术方案路径；独立运行时已有交付说明可一并引用，dev F7 尚未生成本轮交付说明，不要求提供；复审时加「上次审查 v<N>（<日期>）」；没有写「无」}}
+> DocNexus：{{尚未发起询问写「未询问」，dev 内部审查固定写「未询问（由 dev 交付统一处理）」；沉淀后写 workflow-run/docnexus/library/<path>；没有值得沉淀的内容写「无需沉淀」，已询问但未成功入库（含用户拒绝）写「未沉淀」}}
 
 ## 结论摘要 *
 
@@ -41,7 +41,7 @@
 
 ## 需求对照（如有）
 
-<!-- 本分支有开发方案 / 技术方案时填写；没有方案时删掉本节 -->
+<!-- 本分支有方案（plan.md）/ 技术方案时填写；没有方案时删掉本节 -->
 
 - 方案里有、diff 里没有：{{逐条列出，无则写「无」}}
 - diff 里有、方案里没提：{{接口 / 表结构 / 配置 / 依赖变更，请作者确认；无则写「无」}}

package/project-review/references/reporting.md

@@ -0,0 +1,48 @@
+# 报告、运行状态与后续
+
+独立审查开工时只读运行状态；dev 内部调用先读调用约定；进入第 7～9 步时再读报告与后续操作。
+
+## 运行状态
+
+独立运行且确定要落盘完整报告时，先确定目标分支与需求名、绑定需求，按 `<skills>/workflow/references/runs.md` 用 kind `review` 创建／恢复运行，R1～R7 对应 SKILL.md 第 1～7 步；每步完成、等待用户或受阻时保存。报告落盘、自检并交给用户后，将 R7 标 completed 并 complete，记录“已完成”和完成时间。可选沉淀、反馈与后续动作按原规则处理。灵活模式只在对话里审查时不创建运行；dev 内部调用也不另起运行，由 dev 主 agent 把报告结果记录到 F7／B5。
+
+## dev 内部调用
+
+优先由未参与本轮实现的子 agent 执行第 1～7 步；没有子 agent 时由当前会话的 dev 执行同样的步骤，报告「审查者」写当前 agent，不写成独立审查。完整流程必须落盘报告（零发现也写），不使用下文「灵活模式」免落盘；S 快速通道不落盘，不适用本节。跳过第 8～9 步，沉淀与反馈由 dev 交付时统一处理。只审代码、写报告，不修改业务代码、不生成 `delivery.md`、不提交。元信息写「未询问（由 dev 交付统一处理）」，不将 F8 的交付沉淀结果复制到内部审查报告；缺少本轮交付说明是正常时序，需求、已确认决定和验证结果以 dev 交接为准，旧交付说明只作历史参考。报告完成后交回主 agent，由主 agent 询问用户修复或交付。
+
+## 第 7 步 — 输出报告（dev 完整流程的自审同样执行本步，只跳过第 8～9 步）
+
+尚未发起沉淀询问时，报告元信息先写「未询问」。按报告模板输出（`node <skills>/workflow/scripts/resolve.mjs template project-review report.md` 取 `path`），落盘规则见 Artifact Location。
+
+## 第 8 步 — 沉淀到 DocNexus（需用户授权）
+
+交付报告后先判断本次发现里有没有**特别值得记录**的内容：同类问题再次出现（知识库里已有类似沉淀，或本次多处出现）、新确立的编码约定、容易踩的坑。没有 → 不提沉淀，报告的「DocNexus」元信息行写「无需沉淀」；有 → 明确问用户「要不要启动 DocNexus 流程，把本次审查沉淀到 DocNexus？」，并列出建议沉淀的内容；发起询问时将报告元信息改成「未沉淀」，入库成功后再写知识路径。
+   - 用户同意 → 按 DocNexus 入口 skill `docnexus` 的 capture 流程写入；正文只写知识，不写分支、路径；有 facts 时按 `<skills>/workflow/references/docnexus.md`「沉淀的来源」的格式写 provenance；分类用 `node <skills>/workflow/scripts/resolve.mjs category project-review` 的结果作为调用方显式分类封存（见 `<skills>/workflow/references/docnexus.md`「写入 DocNexus 的分类」）。只沉淀问题模式和约定，不沉淀某次审查的逐条清单，也不沉淀「⚠ 待确认」的发现；知识库已有同类沉淀时更新那一篇（带 `--base-version`），不要重复新建。写入成功后把报告的「DocNexus」元信息行改成 `workflow-run/docnexus/library/<path>`（多篇用「、」分隔），并回报给用户。
+   - 用户不同意 → 元信息行保持「未沉淀」。
+   - 元信息更新后运行 `requirement.mjs sync <报告路径>`。
+
+## 第 9 步 — 记录运行反馈（不问用户）
+
+按 `<skills>/workflow/references/feedback.md` 运行 `node <skills>/workflow/scripts/feedback.mjs add --skill project-review --model <模型名> --mode review --depth <快审|标准|深审> --rounds <提问轮数> --corrections <用户纠正审查范围的次数> --findings <C>/<H>/<M>/<L>`，有跳过的步骤、不清楚或做不到的规则、用户的抱怨时再加 `--skipped` / `--unclear` / `--feedback`。只写过程，不写代码和业务名词；报错就提一句，不影响交付。
+
+## Output Template
+
+报告结构以第 7 步取到的报告模板为准：元信息（审查范围、对比分支、审查方式、参考产物、DocNexus）、结论摘要、与上次审查对比（复审时）、严重问题（带触发条件与复核列）、一般问题、优化建议、需求对照（有方案时）、配置清单（如有）、影响面、未覆盖与待确认。某一节没有内容写「无」，不要删标题。
+
+> 灵活模式：单文件 / 小改动只在对话里回复时，可以直接列 findings，不必套完整模板；但每个结论必须指向真实文件+行号并引用代码，不得用"应该/大概"下结论，CRITICAL / HIGH 仍要复核。落盘的报告一律用模板。
+
+## Artifact Location
+
+本节只适用于工作流生成的审查报告。用户只是让看一眼、问个问题，或让写一份不进入需求归档的分析、草稿时，产物默认放项目根的 `workflow-run/other/`（需要时创建，可按主题建子目录），不 `bind`、不调 `run.mjs`，也不写需求 `meta.json`；用户明确指定路径时以用户为准。走本 skill 正式流程产出的审查报告仍按下面的规则归档。
+
+审查报告按需求归档在 `workflow-run/docs/requirements/<需求名>/<项目名>/`，规则见 `<skills>/workflow/references/requirements.md`：
+
+- 路径用 `node <skills>/workflow/scripts/requirement.mjs path review`（分支对比按 dev 分支加 `--branch <dev分支>`），写到输出的 `path`（文件名固定为 `review.md`）；已有报告时脚本先把它归档，输出的 `previous` 是上次报告，复审对照它。
+- 退出码 2（这个分支还没绑定需求）：问用户这个需求叫什么，默认值用输出的 `suggested_name`，再 `requirement.mjs bind --name "<需求名>" [--branch <dev分支>]`；用户不给名字时 `bind` 按分支名生成。
+- 报告同时完整输出到对话；落盘文件与对话内容一致
+- 写完运行 `requirement.mjs sync <path>` 更新 `meta.json`；输出里 `archived` 非空（上一版已归档到 `workflow-run/tmp/old-artifacts/`）时告诉用户归档了哪些文件，请用户确认不再需要后自己删除；输出里 `commit` 非空（独立文档仓库模式）时按 `<skills>/workflow/references/requirements.md`「文档仓库的提交」处理。文档里引用其他产物（「参考产物」等）写 `requirement.mjs path` 输出的 `cite`
+- 写完运行 `node <skills>/workflow/scripts/lint-doc.mjs <报告路径> --skill project-review --facts` 自检：「错误」（缺必填章节、缺元信息行、残留 `{{...}}`）先修正；「在 diff 和代码里都找不到」的名字逐个核实，写错了就改成真实的名字
+
+## 终端命令
+
+本 skill 给出的 `node …`、`git …` 命令在 bash、zsh、PowerShell 里写法一样，原样运行即可。需要自己写其他终端命令时，先看本机的系统和终端：`node <skills>/workflow/scripts/resolve.mjs env`（安装时记录，一次对话查一次就够；`resolve.mjs profile` / `status` 的输出里也带着 `env`）。按输出的 `os`、`shell`、`note` 写命令，不要再用 `uname`、`$PSVersionTable`、`ver` 之类去探测。

package/project-review/references/review-method.md

@@ -0,0 +1,56 @@
+# 范围、背景与逐项审查
+
+进入第 1～5 步时读取对应小节；分批与深审并行策略继续读 diff-strategy.md。
+
+## 第 1 步 — 确定审查范围与深度
+
+范围是单文件 / 单方法、分支对比（如 `branch` vs `main`），还是未提交改动（见 `diff-strategy.md`「未提交改动」）。分支对比和未提交改动都先运行 `node <skills>/workflow/scripts/review-scope.mjs --diff <基线>...<dev>`（未提交改动用 `--base <基线>`，含未跟踪的新文件；dev 自审时加 dev 传来的 `--exclude`），**审哪些文件以它的 `review` 为准**：`skipped` 是按规则跳过的（删除、二进制、敏感文件、依赖目录、生成文件、文档、本工具的产物，各带原因），不要自己再增减；确实要审被跳过的，在画像 `review.include` 里加（见 `<skills>/workflow/references/profile.md`）。深度按用户的说法定，没说就用「标准」，写进报告「审查方式」：
+   - **快审**（「快速看一下」「扫一眼」）：只查正确性、空值、安全、事务与幂等，不查性能、测试、风格；「优化建议（LOW）」写「无」。CRITICAL / HIGH 照样复核。
+   - **标准**（默认）：检查清单全部维度，**风格类（清单「一致性 / 风格」一节）不查**；「优化建议（LOW）」只写有实际收益的（性能、可维护性上的具体问题），没有就写「无」。
+   - **深审**（「仔细审」「全面审」，或资金 / 权限 / 对外接口的大改动合并前）：全部维度，包括风格；MEDIUM 也复核。
+
+## 第 2 步 — 建立理解
+
+先读实体、接口、DTO、调用链，理清数据流再下结论；不要凭文件名猜内容。
+   - **查项目约定（DocNexus）**：先运行 `node <skills>/workflow/scripts/knowledge.mjs project-review --match <模块名 / 业务名词> --query "<一句话：改动涉及的模块与业务>"`，看以往审查沉淀的反复问题和开发约定（`--query` 在这些分类内按正文 recall），找相关的编码约定、历史决策与已知坑，作为审查依据并在报告中引用 `workflow-run/docnexus/library/<path>`。审查过程中**不写入** DocNexus（写入见第 8 步）。
+   - **同分支已有产物**：运行 `node <skills>/workflow/scripts/artifacts.mjs --branch <dev分支>`（单文件 / 未提交改动用当前分支，省略 `--branch`），看输出的 `latest`：
+     - `latest.plan` 或 `latest.tech` 存在 → 读其中的验收标准、改动设计、接口 / 数据 / 配置变更，第 3 步审 diff 时做**需求对照**：方案里有、diff 里找不到的 → 漏实现（属于验收标准的按 HIGH，其余 MEDIUM）；diff 里有、方案里没提的接口 / 表结构 / 配置 / 依赖变更 → 列出请作者确认（不一定是问题）。只对照能在 diff 里核对的项，不推测业务语义。
+     - `latest.delivery` 存在（dev 的交付说明）→ 其中「已确认的决定」并入需求对照的依据；「配置清单」「SQL 脚本」和 diff 对照，diff 里有而交付说明漏列的配置 key / DDL 记为 MEDIUM（上线时会被漏掉）。
+     - `latest.review` 存在 → 这是**复审**：读上次报告的问题表，并用 `git log --oneline --since=<上次报告日期> <dev分支>` 看之后改了什么。本次报告对上次的每条问题标「已修复 / 仍存在 / 不再适用」（「已修复」要看到对应改动），本次新发现的标「新增」。
+   - **涉及数据库**：diff 里有 SQL、Mapper、实体或 DDL 时，按 `<skills>/workflow/references/tables.md` 运行 `node <skills>/workflow/scripts/tables.mjs --diff <基线>...<dev>`（未提交改动用 `--base <基线>`）找出涉及的表；按本轮数据库通道用 `query.mjs --schema --tables <表> --indexes` 只读拉取实际字段、索引与估算行数，作为第 4、6 步判断索引支撑、字段存在与类型、DDL 锁表与滚动发布兼容的依据。查不了库时注明「未与实际库核对」写进「未覆盖与待确认」，这类发现不升到 HIGH 以上，除非 diff 本身就能证明。
+
+## 第 3 步 — 分支对比
+
+基线默认取 `workflow/profile.json` 的 `main_branch`（未配置则 `main`）。规模和分批用第 1 步 `review-scope.mjs` 的输出：`summary.size` 是「全量精读」就一次读完；「分批精读」按 `batches` 的顺序（P0 → P1 → P2）读，P0 不能跳过；「过大」时停下请用户缩小范围。审不到的文件写进报告（读法见 `diff-strategy.md`）。**深审且改动属于「更大」、环境又能派子 agent 时，先问用户要不要分角度并行查找**（`diff-strategy.md`「分角度并行查找」），用户同意才走，第 4 步改由各子 agent 按角度过清单。只审本次改动引入的问题，同时检查改动是否破坏既有调用方。
+
+## 第 4 步 — 逐项过检查清单
+
+每个文件只看 `review-scope.mjs` 给它的 `sections`（清单小节号，按文件类型和改动内容定），一批文件用 `node <skills>/workflow/scripts/review-scope.mjs rules <文件…>`（带上和第 1 步一样的 `--diff` / `--base`）打印这些小节的原文和画像 `review.rules` 里匹配到的项目规则，按它检查；整个改动再过一次 `overall_sections`（9 影响面、13 测试）。深审读整份清单（`node <skills>/workflow/scripts/resolve.mjs template project-review checklist.md` 取 `path`），包括风格。对每个发现给出 文件、**问题所在的原代码片段**（从文件里照原样复制，第 6 步靠它定位行号）、问题描述、严重级别、修改建议。
+
+## 第 5 步 — 影响面分析
+
+改动是否影响其他调用方/模块。按本轮 CodeGraph 通道分析（script 模式运行 `node <skills>/code-graph/scripts/cg.mjs impact --diff <基线>...<dev>`；未提交改动用 `--base <基线>`）：列出受影响的接口、MQ 消费者、定时任务、测试、表和配置 key，报告「影响面」按入口归纳并带文件:行号。Spring 注入、AOP、MyBatis XML、MQ topic、配置 key 图谱看不到，照常 grep（见 `<skills>/workflow/references/codegraph.md`）。查不到调用方的符号不能当作安全，要明说"未确认"。
+
+## 只报会出问题的
+
+报告越短，真问题越不会被漏看。下面这些不报：
+- 风格、命名、格式、注释措辞（快审和标准审查都不报；深审或用户要求时才看）；
+- 编译器、linter、CI 已经会拦下的（未使用的变量、格式、import 顺序）；
+- 个人偏好、没有违反项目约定（`workflow/profile.json` 的 `notes`、DocNexus 约定、审查清单）的写法差异；
+- 写不出后果的「可以更好」：每条发现都要说清不改会怎样。
+
+## Review Dimensions
+
+- 正确性 / 逻辑 bug
+- 字段完整性（实体拷贝是否漏字段、新旧对象赋值是否遗漏、DTO↔实体映射是否缺值）
+- 空指针 / 空值安全
+- 并发与线程安全
+- 异常处理与资源释放（连接、流、锁、事务）
+- 安全（注入 / XSS / 越权 / 敏感信息 / 硬编码密钥）
+- 性能（N+1、循环内查询、大对象、无谓复制）
+- 一致性 / 命名 / 风格（只在深审或用户要求时）
+- 幂等与消息一致性（重复消费 / 回调、事务内发消息）
+- 数据库变更安全（锁表、滚动发布兼容、索引支撑；以实际表结构为准，见第 2 步「涉及数据库」）
+- 测试（改动有没有被测试覆盖、断言是否有效）
+- 语言专项（Java / Go / TS / Python / SQL 各自的常见坑，按改动涉及的语言选读）
+- 配置（见第 4 步取到的审查清单中的配置维度；项目使用的配置中心取自 `workflow/profile.json` 的 `config_center`——配置相关发现按配置清单输出）