@xgent-ai/skills 0.7.4 → 0.7.6

package/skills/review-dev-plan/references/report-contract.md

@@ -1,13 +1,26 @@
 # 问题判定与报告合同
 
+ODC 声明约束评审和报告编写，不复制进报告；下方 Markdown 模板、表格与报告顺序是交付接口。
+
 ## 落盘与交付合同
 
-- **默认保存完整 Markdown 报告**，只有用户明确要求仅聊天或不写文件时才跳过。聊天中的报告正文、拟写入内容或路径预告都不算已落盘。
-- 路径优先级：用户指定路径 → 本地计划同目录的 `<计划文件名去掉扩展名>.review.md`；例如 `docs/plan/cache.md` 对应 `docs/plan/cache.review.md`。输入只有聊天文本或远程文档、没有本地计划文件时，遵循仓库报告目录约定；无约定则写当前工作区的 `docs/reviews/<主题短名>.review.md`。按需创建目录，不因用户未指定路径而停下询问。
-- 写入前检查目标是否已存在。用户已明确要求更新或覆盖该报告时按授权执行；否则保留旧报告，在同目录依次尝试 `<主题>.review.<YYYY-MM-DD>.md`、`<主题>.review.<YYYY-MM-DD>-2.md` 等未占用名称。用户指定路径发生同名冲突时也另存，并在最终回复说明实际路径；不得覆盖原计划或代码。
-- 主 agent 单独写入下文「完整报告顺序」的全部内容，然后回读实际文件，核对问题、待核实项、覆盖与基线、实施编排和总体结论均已保留，检查引用定位与报告路径有效。空 findings、部分证据缺失或 `Blocked` 不免除保存义务，按实际覆盖情况写明限制。
-- 最终聊天回复只给实际报告链接、建议状态和关键问题/待核实项摘要，避免重复整份报告；明确仅聊天时才在聊天中交付完整报告。
-- 无可用文件写入工具或写入失败时，明确说明“报告未落盘”、原因与目标路径，在聊天中提供完整报告以保留结果，并将落盘标为未完成；不能声称已保存或给出不存在的产物链接。
+```formal
+RULE @plan_report_storage:
+  UNLESS: explicit_chat_only_or_no_file_request
+  MUST: ["默认由主 agent 单写完整 Markdown 报告并回读实际文件；空 findings、部分缺证或 Blocked 仍须保存，按覆盖说明限制",
+         "核对问题、待核实、覆盖/基线、实施编排、总体结论、引用和路径齐全有效；已保存后聊天只给实际链接、建议状态和关键问题/待核实摘要"]
+  MUST_NOT: treat_chat_preview_or_path_notice_as_saved_report
+
+RULE @plan_report_path:
+  WHEN: file_report_required
+  MUST: ["路径按用户指定 → 本地计划同目录 <计划文件名去掉扩展名>.review.md，如 docs/plan/cache.md → docs/plan/cache.review.md；仅聊天输入/远程原文按仓库报告目录惯例，无则当前工作区 docs/reviews/<主题短名>.review.md；按需建目录，不因未给路径停下",
+         "写前查同名，已授权更新/覆盖该报告则执行；否则保留旧报告，依次尝试同目录 <主题>.review.<YYYY-MM-DD>.md、<主题>.review.<YYYY-MM-DD>-2.md 等空闲名；用户指定路径冲突也另存并说明实际路径"]
+  MUST_NOT: overwrite_source_plan_or_code
+
+RULE @plan_storage_fallback:
+  MUST: [=>[explicit_chat_only_or_no_file_request, "在聊天交付完整报告"],
+         =>[report_write_tool_unavailable_or_write_failed, "明确报告未落盘、原因和目标路径，聊天保留完整报告，保存标未完成，不声称已保存或链接不存在产物"]]
+```
 
 ## 原文档引用（报告头）
 
@@ -21,9 +34,12 @@
 | 开发计划 | [<原文档标题>](<相对报告所在目录的原文路径或稳定 URL>) | <内容 hash / 可取回版本；不可得则 unknown> | <全文或指定章节/里程碑 ID> |
 ```
 
-- 本地链接按**实际报告所在目录**计算，不能按当前工作目录、仓根或默认报告位置计算；含空格路径使用合法 Markdown 链接语法。不写机器绝对路径，原文位置与文件名不变。另存到指定目录或带日期的报告时重新核对链接。
-- 远程原文用稳定 URL 并注明可用版本；输入只有聊天文本且没有持久原文时，原文档栏写「聊天输入，无原文路径」，不伪造链接，说明 apply 时需可定位的目标。
-- 回读报告时沿引用打开原文，核对类型、身份、版本与范围；原文已变化时说明所审基线及适用性。后续处置保留此处的历史所审版本，修后版本写入处置节。
+```formal
+RULE @plan_source_reference:
+  MUST: ["本地引用相对实际报告目录计算，不按 cwd/仓根/默认报告位置；空格路径用合法 Markdown，原文位置/文件名不变，不写机器绝对路径，另存或加日期后重新核对",
+         "远程原文用稳定 URL 与可用版本；无持久原文的聊天输入写‘聊天输入，无原文路径’，不造链接，并说明 apply 需要可定位目标",
+         "回读时沿链接打开原文，核对类型/身份/版本/范围；原文变化说明基线及适用性，处置保留历史所审版本，修后版本写处置节"]
+```
 
 ## 复审记录
 
@@ -34,18 +50,24 @@
 | 来源报告 / F-ID或稳定章节 | 上轮问题与结论 | 已有处置 / 修后版本 | 本轮结果 | 当前证据 / 验证 | 剩余动作 |
 | --- | --- | --- | --- | --- | --- |
 
-- 本轮结果统一用：**已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**。已解决需符合原问题的关闭判据；回归需有先前解决及当前再次失败的证据；不再适用须有范围/契约变化依据，不代表实际修复。缺证不能记关闭，未选中的旧项标本轮未复核。
-- 来源身份使用“报告路径/原始版本 + F-ID”，有台账时同时保留评审对象 ID；同一链路沿用旧编号。多份报告的同号问题不合并，新问题分配未占用编号并明确属于本轮；同根因合并时保留来源映射，不重新编号抹掉历史。
-- 默认覆盖上轮全部问题及待核实项；用户限定范围时逐项列出未复核项或其完整 ID 清单。读取处置记录后独立核对实际结果，保留旧证据是否仍适用的理由；只检查修复影响到的必要回归，不自动重跑无关全量验证。
-- 总结分别给出“旧问题解决情况”“修复引入的新问题”“未覆盖/缺证范围”。本轮没有新增 findings 不等于旧问题已关闭；部分通过不扩大成整体通过。复审表结果是检查结论，SDLC 回写仍按仓内协议的固定状态与范围登记，不自造 state 枚举。
+```formal
+RULE @plan_recheck_evidence:
+  WHEN: re_review_with_prior_report
+  MUST: ["结果仅用已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核；已解决满足原关闭判据，回归有先前解决及当前再失败证据，不再适用有范围/契约变化依据且不等于实际修复，缺证不关闭，未选旧项标本轮未复核",
+         "来源身份为报告路径/原始版本 + F-ID，有台账再保留评审对象 ID；同链路沿用旧号，多报告同号不混合，新问题用未占用号并注明本轮，同根因合并保留来源映射，不重编号抹历史",
+         "默认覆盖上轮全部问题及待核实，限定范围时逐项列未复核或完整 ID 清单；读处置后独立核实实际结果和旧证据适用性，只查修复影响的必要回归，不自动重跑无关全量验证",
+         "分别总结旧问题解决情况、修复引入的新问题、未覆盖/缺证范围；无新增 findings 不等于旧项关闭，局部通过不等于整体通过；SDLC 按仓内固定状态与范围登记，不造 state 枚举"]
+```
 
 ## 什么进入 findings
 
-确认的问题须同时具备：计划中的可定位主张或缺口、已核实的依据、具体触发/受影响场景、对本期目标的实际后果、可执行的最小修订。建议作者换个人偏好的技术、堆更多章节、覆盖无关老问题，都不算。
-
-“没有写 X”须先确认全文/引用中确实没有，并证明 X 是本期交付必要条件。证据不足的风险放待核实项，写所需证据及影响；关键待核实项仍可阻塞就绪判断，不能伪装成已证实缺陷。
-
-每条只解释一个独立根因。合并重复症状时保留涉及的需求、里程碑和规则来源。无实质影响的拼写、偏好、格式不报；违反适用合同而会造成实施偏差的格式问题说明其后果。
+```formal
+RULE @plan_finding_admission:
+  MUST: ["确认问题同时有计划定位、已核实依据、具体触发/受影响场景、对本期目标的实际后果及可执行最小修订",
+         "断言缺少 X 前查全文/引用确实无 X，并证明为本期交付必要条件；缺证列待核实、所需证据及影响，关键缺口仍可阻塞就绪，不伪装成确认缺陷",
+         "一条一独立根因，合并症状保留需求、里程碑及规则来源；适用合同的格式问题须说明实施偏差后果"]
+  MUST_NOT: "将个人技术偏好、堆章节、无关旧问题或无实质影响的拼写/格式报缺陷"
+```
 
 ## 严重度与置信度
 
@@ -70,7 +92,10 @@
    - 置信度：<高/中 + 原因>；阻塞：<受影响任务/里程碑或否>
 ```
 
-本地文件优先使用可点击路径和短行定位；行号变动大时同时给稳定标题/符号。定位指向原计划有责任承载该要求的位置，不能指向 reviewer 自己新写的报告。代码行号不必位于 git diff 内，计划评审可能没有 diff。
+```formal
+RULE @plan_finding_citations:
+  MUST: "本地优先可点击路径及短行定位，行号变动大补稳定标题/符号；定位到原计划有责任承载要求处，不指向 reviewer 新报告；代码证据不限 git diff，计划评审可能无 diff"
+```
 
 ## 完整报告顺序
 
@@ -94,3 +119,12 @@
 
 - **需要**：有 P0–P2 确认问题；或待核实/待决策项须写进计划（如补登记阻塞、修正前提）；或建议状态与计划自报状态不一致。
 - **无需**：只剩 P3 或无问题，且计划自报状态与建议状态一致。此时仍为 `Blocked` 表示计划已如实登记阻塞，下一步是逐项解除阻塞，不是改稿。
+
+```formal
+REVIEW:
+  CHECK: [@plan_report_storage, @plan_report_path, @plan_storage_fallback, @plan_source_reference,
+          @plan_recheck_evidence, @plan_finding_admission, @plan_finding_citations]
+  ALSO: ["评审对象、问题模板、复审表、严重度及完整报告顺序均遵守本合同",
+         "是否需要修改独立于 Ready/Proposed/Blocked，按影响与证据判定，不以总分或严重度机械替代状态；下一步符合主技能第 5 节"]
+  EXPOSE: on_issue
+```

package/skills/review-dev-plan/references/review-lenses.md

@@ -41,7 +41,8 @@
 - 反查文件、迁移、配置、部署、故障恢复、测试替身和验收准备是否属于已确认开发范围。范围外系统的工作只作外部前置，写清责任与影响开发/集成/终验的哪一段；把它写进本方里程碑、默认排到本项目下一期，或借真实验收建设替代系统，应定位越界项及范围依据。真实集成门仍保留，不能用排除外部实现掩盖交付未闭环。
 - 开发检查是否能由 Agent 用本阶段可获得的资源执行？用户角色应有明确的知识、资料与权限约束，供 Agent 模拟；自行增设真人招募、样本人数或满意度门槛属于可执行性问题。确需真人的指标核对来源、阶段与资源前置，不默认阻塞开发；用户明确指定的开发真人门仍保留，模拟不能冒充真人数据。Agent 能操作的真实环境检查不能仅因没有真人而判受阻，也不能用 mock 替代要求的真实集成。
 - 里程碑退出条件能判定局部结果，阶段收口有跨模块集成与用户主路径验证。允许同能力、同环境且无独立风险门的验收合并，核对检查覆盖、执行时点、收口负责人和前置就绪；骨架阶段不要求尚未实现的端到端路径。安全、迁移、不可逆操作、发布及用户分期门不能被合并绕过，风险不能拖到终验才发现。局部完成不等于阶段/跨期需求已验收，fixture 或构建通过不能替代真实集成、权限、业务或界面验收。反过来，中间里程碑的退出条件排了全量测试、端到端或真实环境走查，或同一收口检查在多个里程碑复跑，会让实施反复跑全量回归，应作为编排问题指出；阶段应是多个里程碑组成的完整功能组合。
-- 完成数、最近完成、下一步、记录链接及基线一致；初稿不预填完成，进行中不计完成。已完成有本里程碑退出检查证据；可按测试组覆盖多条条件，须逐条可追溯，共同环境/基线可只写一次，不默认要求子任务文档。复用证据须有原记录及依据：只有它实际覆盖的代码、契约、配置、依赖或数据被改动才需重跑，全量回归在阶段收口跑。适用 dev-plan 协议时核对逐行退出条件及里程碑记录，不机械否定历史格式。
+- 实现里程碑是否有完整交付批次，局部检查是否写清哪些交付物齐备后执行？批内针对失败、疑问或必要前置的最小反馈，与批次退出的整组局部检查应分开；仅写“开发中跑局部测试”、按文件/函数/goal 对话轮次切批，或把包级测试/typecheck/build 当逐次编辑反馈，仍会导致频繁回归。无独立前置或风险门的碎片应合批，不为每个小改动增设验收点；按实际成本安排命令，不编造耗时。生成计划顶部须带有实施者能直接遵循的节奏，不能只在写作规则里声明。
+- 完成数、最近完成、下一步、记录链接及基线一致；初稿不预填完成，进行中不计完成。已完成有本里程碑退出检查证据；可按测试组覆盖多条条件，须逐条可追溯，共同环境/基线可只写一次，不默认要求子任务文档。复用证据须有原记录及依据：只有它实际覆盖的代码、契约、配置、依赖或数据改变才失效，同批改动合并到下一适用局部退出或阶段收口复验，不能要求一失效就立刻重跑；下游依赖该证据或跨风险门前必须补齐，旧证据不能证明新版通过。续做、汇报、回写、提交本身不触发回归；失败修复仅复验失败项及实际波及范围，共享契约等变化按影响扩大。适用 dev-plan 协议时核对逐行退出条件及里程碑记录，不机械否定历史格式。
 - 提取有向依赖边 `前置任务 → 后置任务` 及其产物；检查循环、缺失节点、倒置、隐藏的跨系统前置和过粗的里程碑阻塞。编号不是依赖，文件分目录也不代表无依赖。
 - 区分开发、集成和终验前置，以及代码、契约、迁移、配置/权限与环境资源依赖。下游只需某个已通过必要检查的成果时，建议将依赖细化到该成果与解锁证据即可，不强制新增里程碑。稳定契约下可用 fixture 开发；无关走查或发布排练不默认阻塞开发，用户分期与风险门仍须遵守。
 

package/skills/review-prd/SKILL.md

@@ -2,39 +2,72 @@
 name: review-prd
 argument-hint: "<PRD路径/链接/内容> [上轮报告] [复审/完整评审] [问题ID/范围] [报告路径] [仅聊天]"
 description: 用于评审既有 PRD 的合理性、产品质量与可验收性；不用于从零写 PRD、评审技术计划或代码 diff。核实代码现状、需求、体验、UAT 与分期，默认落盘报告。
+disable-model-invocation: true
 ---
 
 # review-prd · 基于代码事实的产品需求评审
 
-目标是判断：**在用户约束内，这份 PRD 是否充分设计了值得做、可用且体验好的产品，能否清楚交接「做什么」与「怎样算完成」，它对代码现状和前置能力的认识是否真实。** 评审既检查错误与缺口，也检查有价值的创新和 AI 机会是否被遗漏；不止审文档格式。
+```formal
+INTENT:
+  GOAL: "判断 PRD 在用户约束内是否充分设计值得做、可用且体验好的产品，能否交接做什么/怎样算完成，以及代码现状与前置认知是否真实"
+  SUCCESS: ["错误、缺口及有价值的创新/AI 遗漏均按证据裁定，不只审格式",
+            four_review_lenses_covered, complete_report_with_verified_delivery]
 
-**默认交付是已写入文件并回读核验的完整评审报告，聊天只给摘要和实际文件链接。除非用户明确要求仅聊天或不写文件，否则落盘属于评审任务本身，不额外询问是否保存；未落盘不能宣称交付完成。**
+RULE @prd_default_delivery:
+  UNLESS: explicit_chat_only_or_no_file_request
+  MUST: "将完整报告写入文件并回读核验，聊天给摘要与实际链接；落盘属于评审，不另问是否保存"
+  MUST_NOT: claim_completion_before_report_is_saved
+```
 
 `references/` 相对本文件解析。仓库规则、产品上下文、代码位置、工具和外部依赖在运行时读取，不硬编码目标仓的业务约定。回复语言跟随用户。
 
 ## 边界与参考
 
-- 默认审查整份 PRD；指定差异或局部范围时，同时追踪受影响的场景、需求、验收和分期。原 PRD 与代码保持只读，默认写入为独立评审报告及已启用台账的事实索引（见文末）；不自动实现、改稿、写 SPMS 或发送评论。用户明确要求修订时，先形成可追踪的问题，再统一修订并复核；报告保留处置记录，PRD 正文只保留修订后的产品结论。
-- 区分**现状事实、目标能力、用户/平台约束、未证实假设、验收门槛与观察/PoC 基线**。新能力尚未实现不是 PRD 缺陷；代码当前行为也不是禁止产品演进的理由。报告指出增量与前置，不擅自把当前实现固化为需求。
-- PRD 回答 what / why / 怎样算完成。用户旅程、信息层级、视觉要求、AI 产品行为属于产品设计；内部架构、表结构、端点拆分、模型/算法选型与技术里程碑属于开发计划。UAT 定义角色、场景、预期状态与清晰判据；测试脚本、造数、故障注入、工具及 TC 创建属于测试计划。已给定技术约束、外部产品契约与作为产品能力的评测台可以保留，不能机械按技术词判越界。
+```formal
+RULE @prd_review_scope:
+  MUST: ["默认审整份 PRD；指定差异/局部时追踪受影响的场景、需求、验收与分期，默认只写独立报告及已启用台账的事实索引",
+         =>[explicit_prd_revision_requested, "先形成可追踪问题，再统一修订并复核；报告留处置记录，PRD 正文只留修订后的产品结论"]]
+  MUST_NOT: ["未经明确修订要求改写 PRD", modify_code_or_implement_features,
+             automatic_spms_writes_or_external_comments]
+
+RULE @prd_claim_evidence:
+  MUST: ["区分现状事实、目标能力、用户/平台约束、未证实假设、验收门槛及观察/PoC 基线",
+         "指出真实增量与前置，不把当前实现固化为需求"]
+  MUST_NOT: ["因新能力尚未实现报缺陷", "因代码当前行为禁止产品演进"]
+
+RULE @prd_product_boundary:
+  MUST: ["审 what / why / 怎样算完成，以及旅程、信息层级、视觉与 AI 产品行为；内部架构、表结构、端点、模型/算法选型、技术里程碑交开发计划",
+         "UAT 定角色/场景/预期状态/判据，测试脚本、造数、故障注入、工具和 TC 创建交测试计划",
+         "保留已给定技术约束、外部产品契约与作为产品能力的评测台，不按技术词机械判越界"]
+```
+
 - 在可用时读取 `prd/references/product-quality.md` 校准产品质量规则；采用该模板的文档再按需读 `prd/references/prd-skeleton.md`。找不到 `prd` 时继续按本技能的实质标准评审，不要求安装依赖。用户自定义模板或历史 PRD 不因章节名、编号、缺少 TC 或未录入 SPMS 被判不合格。
 - UI 评审读取目标仓实际适用的产品/设计规范；只有能看到的材料才支持视觉结论。源码、静态稿、原型与浏览器实测分别标注，不把静态推演写成已验证体验。
 
 ## 1. 锚定输入与审查基线
 
-1. 定位用户指定 PRD、原始诉求、已确认约束、关联 PRD 与必要决策。目标无法唯一确定时询问文件/范围，可以先调查仓库规则；不擅自选一份相邻文档评审。
-2. 读取适用的根目录及相关子目录规则、产品与设计上下文。记录 PRD 路径/版本或内容 hash、调查日期、代码仓路径、commit 与 dirty 状态；当前工作树参与调查时明确写出。无 Git 则用可用版本标识；读不到源代码则如实记录证据缺口，继续能做的文档审查。
-3. 提取目标、非目标、角色/权限、业务状态、关键旅程、FR/NFR、UAT/验收、依赖、产品决策、分期与终验关系。无需求 ID 时用稳定章节定位，不补造 SPMS key。只读工具可用时核对关联项目/需求与重复立项情况，不把录入状态当实现状态。
-4. 将会改变产品选择的现状主张和前置条件列入核实清单：声称已支持、未支持、可复用、无需改动、兼容、已验证及性能数字等。标清它们是事实还是未来目标。
-5. 读取 [references/report-contract.md](references/report-contract.md)，确定报告路径；记录四个审查维度及代码核实、报告写入、回读核验的状态。事实能查就先查，只向用户询问无法从证据推出的产品决定；缺少某项输入时继续不依赖它的审查。
+开始时读取 [报告合同](references/report-contract.md)，按其落盘、引用及模式约定执行。
 
-## 修复效果复审
+```formal
+WORKFLOW @prd_review_baseline:
+  DO: ["定位用户指定 PRD、原始诉求、已确认约束、关联 PRD 和必要决策；目标不唯一只问文件/范围，可先查规则，不自选相邻文档",
+       "读适用根/子目录规则及产品/设计上下文，记 PRD 路径/版本或 hash、日期、代码仓路径、commit/dirty，明确当前工作树；无 Git 用可用版本，缺源码留证据缺口并继续文档审查",
+       "提取目标/非目标、角色/权限、状态、旅程、FR/NFR、UAT/验收、依赖、决策与分期/终验；无 ID 用稳定章节，不造 SPMS key；只读工具可用时核对关联及重复立项，录入不等于实现",
+       "将影响产品选择的已支持/未支持/复用/零改动/兼容/已验证/性能等主张与前置列清单，区分事实和未来目标",
+       "确定报告路径，记录四维审查、代码核实、报告写入/回读状态；可查事实先查，只问证据不能推出的产品决定，缺输入继续独立部分"]
+```
 
-用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+## 修复效果复审
 
-- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
-- 当前原文可由上轮报告的“评审对象”引用定位，按报告目录解析相对路径并核实身份；原文参数可在唯一明确时省略。读取已有处置节或 applied 文档，逐项验证原问题和修订影响的关联内容，不把“已 applied”直接当复审通过。
-- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+```formal
+RULE @prd_re_review:
+  WHEN: "用户要求复审 / re-review / 检查修复效果"
+  MUST: ["按报告合同复审；明确要求完整重审时执行完整流程",
+         "按用户指定、当前上下文或明确记录链接找上轮报告，候选不唯一只澄清相关范围，不按文件时间猜选",
+         "默认覆盖上轮全部问题、待核实项和修复直接影响的回归；指定 ID/范围时其余标未复核；缺上轮报告可审当前对象，不声称旧项逐条关闭",
+         "原文可由上轮评审对象引用定位，按报告目录解相对路径并核实身份，唯一明确时可省原文参数；读处置节/applied 文档，独立核对问题与修订关联内容，不以已 applied 判通过",
+         "逐项复审表沿用来源 ID 与上轮链接/版本，默认另存新报告保留历史；启用台账时登记独立评审并关联前轮，局部通过不覆盖未核查范围"]
+```
 
 ```text
 $review-prd docs/PRD-login.md，对照 docs/PRD-login.review.md 复审修复效果，逐项记录结果。
@@ -53,11 +86,20 @@ $review-prd docs/PRD-login.md，对照 docs/PRD-login.review.md 复审修复效
 
 ### 调度规则
 
-- 有多 agent 工具且当前授权允许时实际启动只读 subagents，主 agent 负责综合裁定和报告单写；不能在同一回答中扮演多个角色后宣称独立复核。简单局部文档可用两位 reviewer 各覆盖两个视角，回报分开说明覆盖与结论。模型继承主 agent，不主动覆盖模型或推理档位。
-- 并发数按实际剩余槽位安排，主 agent 也占槽位。只有 4 个总槽位时，先运行 3 个视角，结束后复用空闲 agent 完成第 4 个；更少则分批。工具/授权不允许、用户要求串行时，主 agent 按四个视角顺序审查，如实写执行方式，不能漏掉维度。
-- 初轮给 reviewer 相同基线、用户约束和原始材料，不把预设缺陷或别人的结论当答案。每个 reviewer 只读原 PRD 与代码，不能继续派生 agent，也不写最终报告。
-- 代码可并行只读；共用浏览器或外部环境由一个操作者采集证据。评审不自动跑迁移、种子、部署、收费模型评测或有副作用的业务操作。必要验证按现有授权执行，做不到则报告缺口。
-- 单个 reviewer 失败时重派一次或由主 agent 接管；不能核实的部分进入待核实项，不无限重试。
+```formal
+RULE @prd_review_scheduling:
+  MUST: ["主 agent 在多 agent 工具可用且当前授权允许时实际启动只读 subagents，综合裁定并单写报告；简单局部文档可用两位 reviewer 各覆盖两个视角，分别回报覆盖与结论",
+         "按实际剩余槽位安排，主 agent 也占槽；总槽位为 4 时先运行 3 个视角，再复用空闲 agent 完成第 4 个，更少则分批",
+         "工具/授权不允许或用户要求串行时，主 agent 顺序审四视角并如实记录执行方式，不漏维度",
+         "模型继承主 agent；初轮各 reviewer 获相同基线、用户约束与原始材料，独立调查，不用预设缺陷或别人结论作答案"]
+  MUST_NOT: [simulate_independent_agents_in_one_response, agent_initiated_model_or_reasoning_override,
+             "reviewer 改 PRD/代码、继续派生 agent 或写最终报告"]
+
+RULE @prd_review_resources:
+  MUST: ["代码可并行只读，共用浏览器/外部环境由一个操作者采证；必要验证按现有授权，无法执行记缺口",
+         =>[reviewer_failed, "重派一次或主 agent 接管，无法核实部分列待核实，不无限重试"]]
+  MUST_NOT: "自动运行迁移、种子、部署、收费模型评测或有副作用的业务操作"
+```
 
 ### Reviewer 派发合同
 
@@ -76,26 +118,40 @@ PRD 与基线：{PRD 绝对路径及版本；代码仓根、commit/dirty、日
 
 ## 3. 主 agent 交叉复核与裁定
 
-1. 逐条阅读支持候选问题的 PRD 段落与原始证据，核对角色、作用域、版本和触发条件。文件/函数存在不等于行为可用，多位 reviewer 一致也不等于事实。
-2. 现状核实至少追到 PRD 依赖的用户或外部系统可观察行为：入口/权限、关键业务逻辑、结果与状态反馈；按需求核对租户隔离、分页、重复/冲突、数据保护、失败恢复、AI 权限/预算及依赖。只读到部分链路就标部分核实，不声称端到端可用。
-3. 将证据影响传回相关视角：例如事实侧发现模型调用没有当前主体授权，产品侧复核 AI 前置，体验侧复核不可用状态，验收侧复核判据和分期。只复核受影响链路，不借机设计具体调用方案。
-4. 按根因与修订动作去重，保留所有实质不同的问题。已确认问题进入 findings，低证据主张进入待核实项；纯偏好不算缺陷，有价值但非必要的产品机会单列，不凑问题数或用总分抵消阻塞。
-5. 核对「目标 ↔ 场景 ↔ FR/NFR ↔ 验收 ↔ UAT 状态 ↔ 分期/终验」的一致性。每期要有独立用户价值；承接计划尽量 5–8 个 Milestone，连续性例外 9–10 个须有理由，最多 10 个。PRD 的规模建议不是技术任务表，不能要求其已经拆出 M1…Mn。
-6. 结束前核对 PRD 与相关代码是否并发变化；只重审受影响结论，无法收敛则标待核实。收集或停止仍在运行的 reviewer，再交付。
+```formal
+WORKFLOW @prd_adjudication:
+  DO: ["逐条读候选问题的 PRD 段落与原始证据，核对角色/作用域/版本/触发；文件/函数存在或 reviewer 一致不等于行为事实",
+       "追到入口/权限、业务逻辑、结果/状态等用户或外部系统可见行为；按需求核对租户、分页、重复/冲突、数据保护、恢复、AI 权限/预算及依赖，部分链路只记部分核实",
+       "将事实影响传回产品/体验/验收等相关视角，只复核受影响链路，不设计具体调用方案",
+       "按根因及修订动作去重并保留所有实质问题，确认项进 findings，低证据项待核实，纯偏好排除；非必要高价值机会单列，不凑数或用总分抵消阻塞",
+       "核对目标 ↔ 场景 ↔ FR/NFR ↔ 验收 ↔ UAT 状态 ↔ 分期/终验；每期独立价值，计划尽量 5–8 个 Milestone，9–10 个连续性例外有理由、最多 10 个，不要求 PRD 已拆技术任务 M1…Mn",
+       "交付前核对 PRD/代码并发变化，只重审受影响结论，无法收敛标待核实；收集或停止仍运行的 reviewer"]
+```
 
 ## 4. 输出评审结果
 
-使用 [references/report-contract.md](references/report-contract.md) 的完整报告顺序和落盘合同，**先列问题，再给总体结论与修订顺序**。由主 agent 保存完整报告并回读；空 findings、代码无法访问或结论为「需补证」也要落盘。
+使用 [报告合同](references/report-contract.md) 的完整顺序与字段：先问题，后总体结论和修订顺序。报告头引用原 PRD；代码矩阵、四维/六维覆盖、SMAR/UAT 与分期核查、非阻塞机会均按合同保留。
 
-报告至少包含：
+```formal
+WORKFLOW @prd_report_delivery:
+  DO: ["主 agent 单写完整报告，空 findings、缺源码或需补证也按 @prd_default_delivery 处理",
+       =>[report_saved, "回读实际文件，沿评审对象链接核对原 PRD 身份/版本/范围及实际报告目录下的相对路径，检查全部字段和链接"],
+       "按第 5 节给是否需要修改与下一步；已保存则给实际链接、通过/需修订/需补证及关键摘要，仅聊天则交完整报告，保存失败按 @prd_report_failure 交付未完成结果"]
 
-- 报告头的「评审对象」：原 PRD 的可点击引用、类型、所审版本与范围；本地路径相对实际报告目录，回读时核验，使 `apply-doc-review` 可仅接收报告参数。
-- 按严重度排序且可定位的问题，附用户场景、实际后果、行为级证据、最小产品修订与复核条件。
-- 代码现状核实矩阵、关键依赖和待核实项；区分静态代码、现有测试、实际运行与浏览器证据，不把尚待开发的目标报成当前缺陷。
-- 四维覆盖及六个产品设计维度的实质结论、SMAR/UAT 与分期终验的断链；不因缺少固定章节或 TC 判错。
-- 建议结论 **通过 / 需修订 / 需补证**，写清阻塞范围与解除条件；有价值的非阻塞机会与修订优先顺序。
+RULE @prd_report_limits:
+  MUST: "通过仅表示已核实范围可交给开发/测试计划，不表示功能已实现、性能实测、UI 验证或可直接上线"
 
-**评审通过仅表示在已核实范围内可作为开发/测试计划的输入，不表示功能已实现、性能已实测、UI 已验证或可直接上线。** 最终聊天回复给实际报告链接、结论和关键问题/待核实项摘要。写入失败时说明「报告未落盘」并按合同保留完整内容，不能链接不存在的产物。
+RULE @prd_report_failure:
+  WHEN: report_write_tool_unavailable_or_write_failed
+  MUST: "明确报告未落盘、原因与目标路径，聊天保留完整内容，将保存标未完成，不链接不存在产物"
+
+REVIEW:
+  CHECK: [@prd_default_delivery, @prd_review_scope, @prd_claim_evidence, @prd_product_boundary,
+          @prd_re_review, @prd_review_scheduling, @prd_review_resources, @prd_adjudication,
+          @prd_report_delivery, @prd_report_limits, @prd_report_failure]
+  ALSO: ["结论和证据等级一致，报告合同字段齐全；自定义章节、无 TC 或未录入 SPMS 未被误判为缺陷"]
+  EXPOSE: on_issue
+```
 
 ## 5. 是否需要修改与下一步
 

package/skills/review-prd/agents/openai.yaml

@@ -2,3 +2,5 @@ interface:
   display_name: "PRD 评审"
   short_description: "核实代码现状，审查产品价值、AI、UI、UAT、SMAR 与分期，出报告并判定是否需修改"
   default_prompt: "使用 $review-prd 评审指定 PRD，核实代码现状及关键依赖，将有证据的问题、产品改进建议和结论写入完整评审报告，默认落盘并回读核验；回复报告链接、是否需要修改，以及 apply-doc-review 或 dev-plan 的下一步命令。"
+policy:
+  allow_implicit_invocation: false

package/skills/review-prd/references/report-contract.md

@@ -1,12 +1,26 @@
 # 问题判定与 PRD 评审报告合同
 
+ODC 声明约束评审和报告编写，不复制进报告；下方 Markdown 模板、表格与报告顺序是交付接口。
+
 ## 落盘与交付
 
-- **默认保存完整 Markdown 报告**；只有用户明确要求仅聊天或不写文件时跳过。聊天正文、拟写入内容和路径预告都不算已落盘，不把「是否保存」留作交付前的确认问题。
-- 路径优先级：用户指定 → 本地 PRD 同目录的 `<PRD 文件名去掉扩展名>.review.md`。输入只有聊天文本/远程文档时遵循仓库报告目录惯例，无惯例则写当前工作区的 `docs/reviews/<主题短名>.review.md`。按需建目录，不因未给路径停下。
-- 写入前检查同名。已授权更新/覆盖该报告则执行；否则保留旧报告，依次尝试同目录 `<主题>.review.<YYYY-MM-DD>.md`、`<主题>.review.<YYYY-MM-DD>-2.md` 等未占用名称。用户指定路径冲突也保留旧文件并说明实际路径，不覆盖原 PRD 或代码。
-- 主 agent 单写完整报告并回读实际文件，核对 findings、待核实项、代码矩阵、覆盖、映射/分期、结论和修订顺序齐全；检查引用定位与文件链接。空 findings、缺源码或「需补证」不免除落盘。
-- 最终聊天给实际报告链接、结论与关键摘要；仅聊天模式在聊天交付完整报告。写入工具不可用或失败时明确「报告未落盘」、原因与目标路径，在聊天保留完整结果，将保存标为未完成；不能链接不存在的文件。
+```formal
+RULE @prd_report_storage:
+  UNLESS: explicit_chat_only_or_no_file_request
+  MUST: ["默认保存完整 Markdown 报告，由主 agent 单写并回读实际文件；空 findings、缺源码或需补证仍须保存",
+         "核对 findings、待核实、代码矩阵、覆盖、映射/分期、结论及修订顺序，检查定位与文件链接；已保存后聊天给实际链接、结论和关键摘要"]
+  MUST_NOT: [treat_chat_preview_or_path_notice_as_saved_report, ask_whether_to_save_as_delivery_confirmation]
+
+RULE @prd_report_path:
+  WHEN: file_report_required
+  MUST: ["路径按用户指定 → 本地 PRD 同目录 <PRD 文件名去掉扩展名>.review.md；仅聊天输入/远程原文按仓库报告目录惯例，无则当前工作区 docs/reviews/<主题短名>.review.md；按需建目录，不因未给路径停下",
+         "写前查同名，已授权更新/覆盖该报告则执行；否则保留旧报告，依次尝试同目录 <主题>.review.<YYYY-MM-DD>.md、<主题>.review.<YYYY-MM-DD>-2.md 等空闲名；用户指定路径冲突也另存并说明实际路径"]
+  MUST_NOT: overwrite_source_prd_or_code
+
+RULE @prd_storage_fallback:
+  MUST: [=>[explicit_chat_only_or_no_file_request, "在聊天交付完整报告"],
+         =>[report_write_tool_unavailable_or_write_failed, "明确报告未落盘、原因和目标路径，聊天保留完整结果，保存标未完成，不链接不存在文件"]]
+```
 
 ## 原文档引用（报告头）
 
@@ -20,9 +34,12 @@
 | PRD | [<原文档标题>](<相对报告所在目录的原文路径或稳定 URL>) | <内容 hash / 可取回版本；不可得则 unknown> | <全文或指定章节/需求 ID> |
 ```
 
-- 本地链接按**实际报告所在目录**计算，不能按当前工作目录、仓根或默认报告位置计算；含空格路径使用合法 Markdown 链接语法。不写机器绝对路径，原文位置与文件名不变。另存到指定目录或带日期的报告时重新核对链接。
-- 远程原文用稳定 URL 并注明可用版本；输入只有聊天文本且没有持久原文时，原文档栏写「聊天输入，无原文路径」，不伪造链接，说明 apply 时需可定位的目标。
-- 回读报告时沿引用打开原文，核对类型、身份、版本与范围；原文已变化时说明所审基线及适用性。后续处置保留此处的历史所审版本，修后版本写入处置节。
+```formal
+RULE @prd_source_reference:
+  MUST: ["本地引用相对实际报告目录计算，不按 cwd/仓根/默认报告位置；空格路径用合法 Markdown，原文位置/文件名不变，不写机器绝对路径，另存或加日期后重新核对",
+         "远程原文用稳定 URL 与可用版本；无持久原文的聊天输入写‘聊天输入，无原文路径’，不造链接，并说明 apply 需要可定位目标",
+         "回读时沿链接打开原文，核对类型/身份/版本/范围；原文变化说明基线及适用性，处置保留历史所审版本，修后版本写处置节"]
+```
 
 ## 复审记录
 
@@ -33,18 +50,25 @@
 | 来源报告 / F-ID或稳定章节 | 上轮问题与结论 | 已有处置 / 修后版本 | 本轮结果 | 当前证据 / 验证 | 剩余动作 |
 | --- | --- | --- | --- | --- | --- |
 
-- 本轮结果统一用：**已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**。已解决需符合原问题的关闭判据；回归需有先前解决及当前再次失败的证据；不再适用须有范围/契约变化依据，不代表实际修复。缺证不能记关闭，未选中的旧项标本轮未复核。
-- 来源身份使用“报告路径/原始版本 + F-ID”，有台账时同时保留评审对象 ID；同一链路沿用旧编号。多份报告的同号问题不合并，新问题分配未占用编号并明确属于本轮；同根因合并时保留来源映射，不重新编号抹掉历史。
-- 默认覆盖上轮全部问题及待核实项；用户限定范围时逐项列出未复核项或其完整 ID 清单。读取处置记录后独立核对实际结果，保留旧证据是否仍适用的理由；只检查修复影响到的必要回归，不自动重跑无关全量验证。
-- 总结分别给出“旧问题解决情况”“修复引入的新问题”“未覆盖/缺证范围”。本轮没有新增 findings 不等于旧问题已关闭；部分通过不扩大成整体通过。复审表结果是检查结论，SDLC 回写仍按仓内协议的固定状态与范围登记，不自造 state 枚举。
+```formal
+RULE @prd_recheck_evidence:
+  WHEN: re_review_with_prior_report
+  MUST: ["结果仅用已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核；已解决满足原关闭判据，回归有先前解决及当前再失败证据，不再适用有范围/契约变化依据且不等于实际修复，缺证不关闭，未选旧项标本轮未复核",
+         "来源身份为报告路径/原始版本 + F-ID，有台账再保留评审对象 ID；同链路沿用旧号，多报告同号不混合，新问题用未占用号并注明本轮，同根因合并保留来源映射，不重编号抹历史",
+         "默认覆盖上轮全部问题及待核实，限定范围时逐项列未复核或完整 ID 清单；读处置后独立核实实际结果和旧证据适用性，只查修复影响的必要回归，不自动重跑无关全量验证",
+         "分别总结旧问题解决情况、修复引入的新问题、未覆盖/缺证范围；无新增 findings 不等于旧项关闭，局部通过不等于整体通过；SDLC 按仓内固定状态与范围登记，不造 state 枚举"]
+```
 
 ## 什么进入 findings
 
-确认的问题同时具备：PRD 可定位的主张/缺口、已核实依据、具体用户场景/触发、对已确认目标的实际后果、可执行的最小产品修订。每条一个独立根因，重复症状合并但保留关键定位。纯格式、偏好或无关旧代码问题不进入 findings。
-
-「没有写 X」先查正文、引用、附录及已确认约束，证明 X 是本产品目标的必要条件；章节标题不同不算缺失。新功能未实现不算 PRD 错误；可确认的前置误判、虚假现状或缺少产品增量才是问题。源码未定位、依赖未联调不是「能力不存在」的证据。
-
-证据不足的主张放待核实项，写需什么证据及对结论的影响；关键证据缺口仍可阻塞通过。高价值且在约束内的增强机会有依据则单列提案，不能把每个合理备选都报成缺陷，更不能借评审自行增加产品承诺。
+```formal
+RULE @prd_finding_admission:
+  MUST: ["确认问题同时有 PRD 定位、已核实依据、具体用户场景/触发、对已确认目标的实际后果及可执行最小产品修订；一条一独立根因，重复症状合并并保留关键定位",
+         "断言缺少 X 前先查正文/引用/附录/确认约束，并证明 X 为目标必要条件；前置误判、虚假现状或缺少产品增量有证据才报问题",
+         "证据不足列待核实，写所需证据与结论影响，关键缺口仍可阻塞通过；约束内有依据的高价值非必要机会单列提案"]
+  MUST_NOT: ["将纯格式、偏好、无关旧代码或不同章节标题报缺陷", "将新功能未实现报 PRD 错误",
+             "凭源码未定位或依赖未联调断言能力不存在", "将所有合理备选报缺陷或自行增加产品承诺"]
+```
 
 ## 严重度与置信度
 
@@ -69,7 +93,10 @@
    - 置信度：<高/中 + 依据>；阻塞：<目标/需求/交接范围或否>
 ```
 
-本地引用使用可点击文件链接与短行定位，必要时补稳定标题/符号；定位指向原 PRD 应承载要求的位置，不指向 reviewer 自己的新报告。只引用读过的原文，截断内容先补读；不能把外部例子数字当成本产品承诺。
+```formal
+RULE @prd_finding_citations:
+  MUST: "本地用可点击文件链接与短行定位，必要时补稳定标题/符号；定位到原 PRD 应承载要求处，不指向 reviewer 新报告；只引已读原文，截断先补读，不把外部例子数字当产品承诺"
+```
 
 ## 完整报告顺序
 
@@ -92,3 +119,12 @@
 状态按影响与证据判断，不能靠总分平均。纯产品方向已经足够明确、技术实现选择留给开发计划时，不因尚无架构方案阻塞 PRD；核心依赖能力是否存在/授权/适配仍须核实。
 
 评审通过不表示功能已实现、线上部署、性能达标、UI 已通过浏览器验收，也不自动批准需求或变更 SPMS 状态。
+
+```formal
+REVIEW:
+  CHECK: [@prd_report_storage, @prd_report_path, @prd_storage_fallback, @prd_source_reference,
+          @prd_recheck_evidence, @prd_finding_admission, @prd_finding_citations]
+  ALSO: ["评审对象、问题模板、复审表、严重度及完整报告顺序均遵守本合同",
+         "是否需要修改、通过/需修订/需补证与证据及阻塞范围一致，下一步符合主技能第 5 节"]
+  EXPOSE: on_issue
+```

package/skills/review-prd-dev-gaps/SKILL.md

@@ -2,6 +2,7 @@
 name: review-prd-dev-gaps
 argument-hint: "<已完成开发计划...> [PRD] [上轮报告] [复审/完整核查] [G-ID/范围] [仅报告] [报告路径]"
 description: 用于开发完成后的 PRD 覆盖核查；不用于 PRD 质量、计划设计或单次 diff 评审。对照已完成计划、记录和实现，区分遗漏与变更，交互裁定差异，必要时生成 gaps plan。
+disable-model-invocation: true
 ---
 
 # review-prd-dev-gaps · PRD 与开发交付差异核查

package/skills/review-prd-dev-gaps/agents/openai.yaml

@@ -2,3 +2,5 @@ interface:
   display_name: "PRD 开发差异核查"
   short_description: "核对 PRD、完成计划与实际交付，分流遗漏、合理变更和用户决策，按需生成 gaps plan"
   default_prompt: "使用 $review-prd-dev-gaps 核对指定已完成开发计划（从其需求来源定位 PRD 与期次），追读里程碑记录并核实实际实现，保存三类差异报告；交互确认需 Triage 的差异，有 follow-up 时调用 dev-plan 创建 gaps plan，并提示用 review-dev-plan 评审。"
+policy:
+  allow_implicit_invocation: false