@xgent-ai/skills 0.6.0 → 0.7.1

package/skills/resolve-blocked/references/decisions-contract.md

@@ -0,0 +1,82 @@
+# 阻塞决策记录合同
+
+## 路径与续写
+
+- 路径优先级：用户指定路径 → 本地计划同目录的 `<计划文件名去掉扩展名>.decisions.md`；例如 `goal/LOGIN.md` 对应 `goal/LOGIN.decisions.md`。计划只有远程链接或聊天文本时，遵循仓库文档目录约定；无约定则写 `docs/plan/<主题短名>.decisions.md`。按需创建目录。
+- 每份计划只维护一份决策记录，多次运行按轮次续写。已存在时读取后续写：沿用已有 B-ID，新增项分配未占用编号；已确认的决定不改写。新决定推翻旧决定时，旧条目保留并标注“被 B-xx 取代”，新条目写明取代原因。
+- 每轮在「处理轮次」追加一行；阻塞总览的结果列只写最新状态并注明轮次；逐项记录的后续轮次结论追加在条目末尾，不改写前几轮。「未解除阻塞」与「就绪结论」反映最新一轮。无实质变化的重跑不追加轮次。
+- 本地链接相对**记录所在目录**计算，不写机器绝对路径。
+- 无法写入时说明“决策记录未落盘”、原因与目标路径，并在聊天中给出完整内容；不声称已保存。
+
+## 文档结构
+
+```markdown
+# <计划标题> · 阻塞决策记录
+
+## 对象
+
+| 类型 | 文档 |
+| --- | --- |
+| 开发计划 | [<计划标题>](<相对路径>) |
+| 评审报告（仅在读取时列出，只读） | [<报告标题>](<相对路径>) |
+
+## 处理轮次
+
+| 轮次 | 日期 | 计划版本（处理前 → 后） | 代码基线 | 本轮解除 | 新增/重开 | 仍阻塞 | 计划状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 第 1 轮 | <YYYY-MM-DD> | <hash> → <hash；未修改则同前> | <commit SHA，clean / dirty 及相关路径> | <B-ID；无写 —> | <B-ID；无写 —> | <B-ID；无写 —> | <处理前> → <处理后> |
+
+## 阻塞总览
+
+| B-ID | 阻塞事项 | 来源定位 | 阻塞范围 | 类型 | 结果（最新） | 计划落点 |
+| --- | --- | --- | --- | --- | --- | --- |
+| B-01 | <一句话> | <计划 §/行；报告 F-ID> | <R/M/任务> | 事实可查/需要决策/外部依赖 | <状态 + 轮次，如「已解除（用户确认，第 2 轮）」> | <计划章节；未修改写 —> |
+
+## 逐项记录
+
+### B-01 · <标题>
+
+- 来源：<计划定位；评审报告路径 + F-ID；疑似阻塞写“未标注，用户 YYYY-MM-DD 确认纳入”>
+- 阻塞范围：<受影响的需求/里程碑/任务，以及最晚卡在哪一步>
+- 上下文：<为什么阻塞，缺什么证据或决定>
+- 已核实事实：<行为 + `路径:行号`；推翻计划前提的单独指出>
+- 约束：<用户原话/PRD/C-*/仓库规则>
+- 选项：
+
+  | 选项 | 做法 | 后果与代价 |
+  | --- | --- | --- |
+  | A（推荐） | | |
+  | B | | |
+
+- 推荐与理由：<选哪个、基于哪些证据与约束>
+- 结论：<状态>；<用户 YYYY-MM-DD 选择 X / 用户授权按推荐 / 证据解除>；用户原话：“<摘录>”
+- 计划修订：<改了哪些章节、改成什么>
+- 复核：<回读后确认的一致性；仍缺的检查>
+- 第 <n> 轮：<后续轮次的核对与结论，如「解除条件已满足，已解除」「仍等供应商答复」「落点被删改，重新打开」；首轮处理的条目没有这一行>
+
+## 未解除阻塞
+
+| B-ID | 缺什么 | 解除条件 | 负责人 | 最晚确认点 | 可先推进的独立工作 |
+| --- | --- | --- | --- | --- | --- |
+
+## 就绪结论（最新一轮）
+
+- 计划状态：<本轮处理前> → <本轮处理后>
+- 理由：<剩余阻塞是否影响范围、安全、数据、外部契约或关键 NFR>
+- 再次运行前需要：<仍阻塞时，各项的解除条件；Ready 时写「无」>
+```
+
+事实可查的项可省略“选项”和“推荐与理由”，结论写证据。负责人未知写“待指定”，不虚构承诺。
+
+## 结果状态
+
+| 状态 | 使用条件 |
+| --- | --- |
+| 已解除（证据） | 查证得到足够事实，计划已据此修订 |
+| 已解除（用户确认） | 用户明确选择或授权按推荐，计划已据此修订 |
+| 降为非阻塞 | 用户确认或证据表明不影响开工，计划已移出阻塞并保留风险项 |
+| 不再适用 | 范围调整等使该项失去意义，写明依据；不等于已解决 |
+| 重新打开 | 已解除项的计划落点被删改或推翻，需要重新处理；保留原结论并写明依据 |
+| 仍阻塞 | 缺证据、外部依赖未到位，或用户未作答 |
+
+只有用户的明确回答才能形成“用户确认”；默认值、空回答、超时一律记为仍阻塞。

package/skills/review-code/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-code
-argument-hint: "[未提交/commit/A..B/基准分支] [上轮报告] [复审/完整评审] [问题ID/文件范围] [开发计划] [报告路径] [仅聊天]"
-description: 用于评审代码 diff、提交或分支差异及修复效果复审；不用于单独评审计划、全仓普查或直接修复。逐项核对旧问题与新增回归，默认落盘有证据的报告。
+argument-hint: "[开发计划] [未提交/commit/A..B/基准分支] [上轮报告] [复审/完整评审] [问题ID/文件范围] [报告路径] [仅聊天]"
+description: 用于评审代码 diff、提交、分支差异或开发计划登记的提交及修复复审；不用于单独评审计划、全仓普查或直接修复。核对旧问题与新增回归，落盘报告并判定是否需修改。
 ---
 
 # review-code · 代码变更评审
@@ -15,13 +15,13 @@ description: 用于评审代码 diff、提交或分支差异及修复效果复
 ## 1. 确定审查对象
 
 1. 读取适用的仓库和子目录指令、review 专项约定。用一句话概括变更意图，区分用户明确要求与从代码推断的意图；缺少提交说明不自动中止评审。
-2. 按 [references/git-scopes.md](references/git-scopes.md) 解析输入，固定仓库根、模式、base/target SHA、工作树快照、文件限制与可选计划版本。未指定模式且存在未提交变更时，声明采用 uncommitted；初审时工作树干净且没有明确对象则询问目标，不擅自选择最近 commit 或默认主分支。修复效果复审按下节核对旧问题，不以存在新 diff 为前提。
+2. 按 [references/git-scopes.md](references/git-scopes.md) 解析输入，固定仓库根、模式、base/target SHA、工作树快照、文件限制与可选计划版本。只给开发计划、未另指定模式时采用其「开发计划模式」：从计划完成记录登记的提交及当前未提交变更确定范围。其他情况未指定模式且存在未提交变更时，声明采用 uncommitted；初审时工作树干净且没有明确对象则询问目标，不擅自选择最近 commit 或默认主分支。修复效果复审按下节核对旧问题，不以存在新 diff 为前提。
 3. 用户给出的模式冲突、ref 不存在或范围端点含义无法确定时，先澄清该部分；可继续读取规则。不要静默替换基准或扩成整仓审查。
 4. 读 [references/report-contract.md](references/report-contract.md) 确定报告路径。建立简短覆盖清单：变更文件/行为、必要上下游、计划范围（若有）、验证方式、证据缺口、落盘和回读。
 
 ## 修复效果复审
 
-用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+用户要求“复审 / re-review / 检查修复效果”时启用；开发计划模式下已有本计划的代码评审报告时也默认启用，以轮次最大的报告为上轮。要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文、报告轮次或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
 
 - 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
 - 复审分两部分：按上轮报告逐项核对当前代码中的旧问题；按本次修复 diff 检查新引入或激活的问题。旧问题的复核不要求落在本次 diff，也不要求由本次修复引入；仍存在的旧问题列复审表并影响修复有效性结论，不冒充本轮新增 finding。
@@ -63,12 +63,28 @@ $review-code BASE_SHA..FIXED_SHA，对照 goal/LOGIN.code-review.md 复审修复
 
 1. 按报告合同写精确短定位、单段问题说明、P0–P3 和置信度。新增 findings 的主定位须与所审 diff 重叠；旧问题复审及支持证据可在 diff 之外。规则对结论有实质贡献时，附该规则的文件和最小行范围。
 2. 核对覆盖清单以及版本是否发生变化。相关文件或计划变动时重审受影响结论；不能收敛时保留快照版本与缺口。报告新文件不纳入本轮审查对象。
-3. 完整报告先列确认问题，再列待核实项、覆盖与验证、可选计划符合性、总体结论和修复顺序。默认采用 `patch is correct / patch is incorrect / inconclusive`；最后一项是本 skill 为证据不足增加的状态，不伪称原生 Codex JSON 值。
+3. 完整报告先写评审对象，再列确认问题、待核实项、覆盖与验证、可选计划符合性、总体结论和修复顺序。默认采用 `patch is correct / patch is incorrect / inconclusive`；最后一项是本 skill 为证据不足增加的状态，不伪称原生 Codex JSON 值。总体结论首行写验收判定。
 4. 写入并回读报告，检查问题、证据、基线、限制和结论完整，链接指向实际文件。空 findings 或无法充分验证也要保存；写入失败如实说明未落盘，聊天交付完整内容，不能宣称完成保存。
 
+## 5. 验收判定与下一步
+
+计划实施完成后，代码评审是验收守门：「评审 → 修复 → 复审」循环，直到通过验收或用户明确本期放过。最终回复先给一行验收判定（定义见[报告合同](references/report-contract.md)的「验收判定」），再给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex `$apply-code-review`、Claude Code `/apply-code-review`），路径填实际文件。
+
+| 验收判定 | 下一步 |
+| --- | --- |
+| 需要修改 | `apply-code-review <本报告路径>`；修复后再用本技能复审 |
+| 通过验收 / 用户豁免通过 | 变更涉及界面、且还没有覆盖当前版本的 UI 验收通过时，可选 `review-ui <计划路径>` 做 UI/UX 验收；计划来自 PRD 时，可选 `review-prd-dev-gaps <计划路径>` 核对该期 PRD 覆盖；都不适用时说明本计划代码验收完成 |
+| 需补证 | 列出所缺证据或验证及获取方式，补齐后再次 `review-code <计划路径或原范围>` |
+
+- 计划是否来自 PRD 以计划顶部「需求来源」为准；旧计划没有该行时，账本来源明确指向 PRD 的也算。未附计划时不提示差异核查。
+- 通过验收但仍有 P3 时，可选用 `apply-code-review <本报告路径>` 处理，处理后照常复审。
+- 用户在评审后或调用时明确表示本期放过剩余问题，按报告合同在本轮报告追加豁免记录并回读，再按通过给下一步；不把豁免写成已修复。
+- 只给出建议命令，不自行启动修复、复审、UI 验收或差异核查。
+
 调用示例（自然语言参数，不要求专用解析器）：
 
 ```text
+使用 $review-code goal/LOGIN.md
 使用 $review-code 审查当前未提交变更。
 使用 $review-code 审查未提交的 src/auth.ts 和 tests/auth.test.ts。
 使用 $review-code 审查 commit abc1234，参考 docs/plan/login.md 的 M2。

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "代码变更评审"
-  short_description: "审查未提交、commit、范围或分支差异，可附开发计划，默认落盘完整报告"
-  default_prompt: "使用 $review-code 审查指定代码变更，核查可选开发计划，按 P0–P3 输出有证据的问题，将完整报告落盘并回读核验，回复结论摘要与报告链接。"
+  short_description: "审查开发计划登记的提交、未提交、commit、范围或分支差异，给出验收判定"
+  default_prompt: "使用 $review-code 审查指定开发计划登记的提交与未提交改动，或指定的代码变更，按 P0–P3 输出有证据的问题，将完整报告落盘并回读核验；回复验收判定、报告链接，以及 apply-code-review 或差异核查的下一步命令。"

package/skills/review-code/references/git-scopes.md

@@ -29,6 +29,17 @@
 - unmerged index 要明确记录；可以审查确定部分，但 unresolved conflict 不等于完整可运行快照，不给出无保留正确结论。
 - 用户限定文件时只对限定文件的变更出 findings，读取相关文件证明影响；另发现范围外线索可列覆盖建议，不静默扩大任务。
 
+## 开发计划模式
+
+只给开发计划、未另指定上述模式时，用计划确定审查对象：
+
+1. 从计划「完成记录」的「提交」列收集提交：普通 SHA 是实现提交，「修复」后的 SHA 是代码评审修复提交，「UI修复」后的 SHA 是 UI 验收修复提交，「待提交」表示改动仍在工作树。逐个用 `git rev-parse --verify --end-of-options '<sha>^{commit}'` 解析为完整 SHA，用 `git merge-base --is-ancestor <sha> HEAD` 确认在当前分支；解析失败或不在当前分支时记录缺口，只用可确认部分。旧计划没有「提交」列时，用计划及其记录中明确写出的提交 SHA；仍无法确定范围就询问，不按时间或作者猜。
+2. 用 `git rev-list --reverse <最早登记提交>^..HEAD` 列出区间内全部提交。只改本计划文件、其记录目录或同名评审/决策文档（含 UI 验收的目标包、报告与截图）的提交是进度回写，不纳入代码审查；其他未登记提交列出 SHA、标题与文件后询问是否纳入，无法交互时只审登记提交并在覆盖中说明。
+3. 初审（本计划尚无代码评审报告）：登记提交在当前分支上连续（中间只有进度回写提交）时，审查 `<最早登记提交>^1..<最新登记提交>` 的净差异；夹杂未纳入的提交时逐个审查登记提交，避免把无关改动混入 findings。
+4. 复审（已有本计划的代码评审报告，轮次见报告合同）：上轮取轮次最大的报告，修复差异从它所审的目标提交起算到当前 HEAD；登记为「修复」「UI修复」的提交分别标为评审修复与 UI 验收修复，上轮未覆盖的登记提交一并纳入新增问题检查。上轮审过未提交内容时，说明它们可能已进入后续提交。
+5. 两种情况都把当前工作树的未提交变更（tracked 净差异与 untracked，按上文「未提交与分支模式」取证）纳入并单列；只改计划、记录或评审报告（含 UI 验收的目标包与截图）的变更不作为代码 findings 对象。没有登记提交且工作树没有代码改动时，说明没有可审变更，不擅自改审最近的提交。
+6. 记录最终范围：各提交完整 SHA、比较方式、未提交指纹、排除的提交及原因。
+
 ## 固定版本与行号
 
 - 记录原始输入和解析后的完整 SHA、实际比较方式、dirty 状态、纳入文件清单；工作树/index/untracked 使用内容 hash 或等价可复查快照，不能只靠 `git status` 判断内容未变。包括影响结论的上下游文件与附带计划。

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

@@ -5,9 +5,20 @@
 - 默认保存完整 Markdown 报告；只有用户明确要求仅聊天/不写文件时跳过，不询问是否保存。
 - 路径优先级：用户指定路径 → 附带的本地计划同目录 `<计划名去扩展名>.code-review.md` → 仓库既有报告目录 → 当前工作区 `docs/reviews/<主题>.code-review.md`。无本地计划时，主题可用 `uncommitted`、`commit-<短SHA>`、`range-<短A>-<短B>` 或 `against-<基准分支短名>`；将分支中的 `/` 等路径字符转换为 `-`，不把 ref 直接作为目录。
 - 写前检查文件已存在与否。仅在用户明确授权更新/覆盖该报告时覆盖；否则另存 `<主题>.code-review.<YYYY-MM-DD>.md`、`<主题>.code-review.<YYYY-MM-DD>-2.md` 等未占用名称。指定路径冲突也遵守此规则，最终说明实际路径。不得把报告写到代码或原计划文件，即使名字碰巧一致。
+- 附带本地开发计划且用户未指定路径时按轮次命名，替代上条的日期后缀：首轮 `<计划名去扩展名>.code-review.md`，之后 `<计划名去扩展名>.code-review.r<n>.md`，n 取已有最大轮次加 1；已有的日期后缀报告按其上轮链接排入轮次。每轮另存，不覆盖旧轮次，下一轮据此确定上轮报告。
 - 由当前主 agent 单独写入完整报告，回读实际文件核对内容与定位。空 findings、`inconclusive` 和部分覆盖不免除落盘。不要只写摘要或拼接未经裁定的 reviewer 回报。
 - 最终聊天给实际文件链接、总体结论和重要问题/限制摘要。写入失败时明确“报告未落盘”、原因和目标路径，聊天提供完整报告以保留结果，落盘仍标未完成；不链接不存在的文件。
 
+## 评审对象（报告头）
+
+报告标题后、findings 前写「评审对象」，复审也保留；`apply-code-review` 仅凭报告即可定位计划和范围：
+
+| 轮次 | 开发计划 | 审查范围 | 上轮报告 |
+| --- | --- | --- | --- |
+| R<n>；未附计划可省略 | [<计划标题>](<相对报告所在目录的计划路径>)；未附计划写「无」 | <base..target 完整 SHA 或逐个提交；含未提交时写工作树指纹> | [<上轮报告>](<相对路径>)；初审写「无」 |
+
+本地链接按实际报告所在目录计算，不写机器绝对路径；回读时沿链接核对计划身份。
+
 ## 复审记录
 
 复审报告在标题及评审对象之后注明：上轮报告的相对链接与版本、所审对象的前后版本、本轮范围、已有处置记录链接，以及“修复效果复审”或“完整重审”。历史报告与原结论保持不变；默认按本合同另存新报告。
@@ -59,7 +70,7 @@
 2. **待核实/待决策项**：缺少什么证据、影响哪个结论、如何补证；无法访问的文件/环境、需求歧义、尚未运行的关键验证放这里。
 3. **覆盖与验证**：一句话意图；仓库根与日期；原输入、解析 SHA、比较方式、工作树/index 指纹或快照、文件限制、纳入/排除项；已审行为链与未覆盖部分；实际命令、目标版本、结果、失败原因。区分静态、测试、浏览器与外部资料证据；注明实际 reviewer 分工（若有）。
 4. **计划符合性（有计划才写）**：计划路径和版本、本次任务/里程碑；仅列相关需求的映射和缺口，包含未核实及后续范围。不要复制整份计划或更新其进度。
-5. **总体结论与修复顺序**：结论、1–3 句理由与覆盖限制；优先解除契约/数据/安全根因，再修局部行为，最后验证相关回归。明确解除阻塞的可观察条件，不把评审结论当作 merge/deploy 授权。
+5. **总体结论与修复顺序**：首行写验收判定（见下文），再写结论、1–3 句理由与覆盖限制；优先解除契约/数据/安全根因，再修局部行为，最后验证相关回归。明确解除阻塞的可观察条件，不把评审结论当作 merge/deploy 授权。
 
 ### 正确性结论
 
@@ -70,3 +81,14 @@
 空 findings 不自动等于正确；未运行全量测试也不自动等于不可裁定，依据关键行为的实际证据判断。报告落盘成功与代码是否正确是两个不同结论。
 
 修复效果复审另给 `已解决 / 未完全解决 / 无法判定` 的修复结论：全部选定旧问题有关闭或有依据的不再适用结论、且相关回归无阻塞，才能判已解决并分别统计实际解决与不再适用。尚有确定未解决项或阻塞回归则未完全解决；关键项仅缺证则无法判定。patch 结论只覆盖声明的 diff，不能用修复增量的 patch is correct 掩盖旧问题仍存在。没有新 diff 时可省略 patch 结论，仍交付旧问题的复审结论。
+
+### 验收判定
+
+由上述结论推出，写在总体结论首行，最终回复也先给它：
+
+- **需要修改**：`patch is incorrect`、复审修复结论为未完全解决，或仍有 P0–P2 问题（含复审中仍存在、部分解决或回归的旧问题）。
+- **通过验收**：没有 P0–P2 问题，所选旧问题已解决或有依据不再适用，证据足以支撑判断；P3 不阻止通过。
+- **需补证**：`inconclusive`、复审无法判定，或没有可审变更；写明所缺证据或验证及获取方式。
+- **用户豁免通过**：用户明确表示本期放过剩余问题。在本报告结论追加豁免记录：日期、用户原话、豁免的 F-ID 及剩余影响；问题与原判定不改写，豁免不算修复。
+
+验收判定只覆盖所审提交与工作树，不是合并、发布或需求验收授权。

package/skills/review-dev-plan/SKILL.md

@@ -19,7 +19,7 @@ description: 用于评审既有开发计划、技术方案或开工条件；不
 - 从实际可用位置读取 `dev-plan/SKILL.md` 的写作/评审部分及 `references/plan-skeleton.md`；复杂架构按需读 `references/architecture-quality.md`，调度审查按需读 `references/execution-workflow.md`；实施期合同以骨架的「实施者定位」「实施进度」两节为准。借它们核对合同，不按计划实施。
 - 找不到 `dev-plan` 时说明无法核对其模板专属要求，继续本技能的四项实质审查。用户自定义模板或历史计划不因章节名不同而报错；没有证据表明适用的新版格式规则，不追溯强加。
 - 新版 `dev-plan` 允许单份需求映射、检查 ID 引用、按测试组记录证据及阶段集中验收；按 `references/review-lenses.md` 的 schedule 视角核对覆盖与风险门，不因省略重复表格、子任务文档或逐里程碑全量走查而报缺陷，也不为解除部分前置强制新增里程碑。
-- 发现与任务相关的专项 skill 时只加载所需部分。UI/UX 评审按目标仓规则加载设计 skill（如 `impeccable`），不借机重设计产品。
+- 发现与任务相关的专项 skill 时只加载所需部分。UI/UX 评审按目标仓规则加载设计 skill（如 `phoenix-ui`），不借机重设计产品。
 
 ## 1. 锚定输入与审查基线
 
@@ -101,6 +101,18 @@ $review-dev-plan goal/LOGIN.md，对照 goal/LOGIN.review.md 复审修复效果
 
 交付前确认：报告已写入并回读、内容符合上述合同、文件链接指向实际产物。最终回复给出报告链接、建议状态及关键问题/待核实项摘要；用户明确要求仅聊天时，直接在聊天中交付完整报告。写入失败时按落盘合同说明未完成项，不把聊天摘要算作完成。
 
+## 5. 是否需要修改与下一步
+
+报告总体结论与最终回复都先给一行明确判定（条件见[报告合同](references/report-contract.md)的「是否需要修改」），再给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex `$apply-doc-review`、Claude Code `/apply-doc-review`），路径填实际文件。
+
+| 判定 | 下一步 |
+| --- | --- |
+| **需要修改** | `apply-doc-review <本报告路径>`：核实并修订计划，处置后判定 Blocked 或 Ready |
+| **无需修改 · Blocked** | `resolve-blocked <计划路径>`：逐项解除计划中已如实登记的阻塞 |
+| **无需修改 · Ready** | `/goal 按 <计划路径> 开发` |
+
+只剩 P3 时仍判无需修改，可选用 `apply-doc-review <本报告路径>` 采纳。计划与建议均为 `Proposed` 时，写明仍在等哪项用户指定的非阻塞评审，不默认给 `/goal`。仅聊天模式没有报告文件时，说明需先落盘报告才能交给 apply-doc-review。只给出建议命令，不自行启动下一步。
+
 ## 项目状态回写
 
 若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。

package/skills/review-dev-plan/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "开发计划评审"
-  short_description: "多 agent 核查代码事实、技术方案、依赖编排与交付可用性，默认落盘报告"
-  default_prompt: "使用 $review-dev-plan 评审指定开发计划，将有证据的问题、就绪结论和可并行的实施编排建议写入完整评审报告，默认落盘并回读核验，回复报告链接与摘要。"
+  short_description: "多 agent 核查代码事实、技术方案、依赖编排与交付可用性，判定是否需修改"
+  default_prompt: "使用 $review-dev-plan 评审指定开发计划，将有证据的问题、就绪结论和可并行的实施编排建议写入完整评审报告，默认落盘并回读核验；回复报告链接、是否需要修改，以及 apply-doc-review、resolve-blocked 或 /goal 的下一步命令。"

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

@@ -78,7 +78,7 @@
 2. **待核实/待决策**：每项写缺什么证据、影响哪个决定/任务、谁可提供以及最晚确认点；责任人未知就写待指定，不虚构用户承诺。
 3. **覆盖摘要**：记录计划与代码基线、实际 agent 分工、四维覆盖/跳过理由、脚本及浏览器实际执行情况。只列结论相关来源，不倾倒阅读日志。无 UI 可写不适用；交付可用性不能随 UI 一起跳过。
 4. **映射与实施编排**：列断链 ID 或确认映射完整的核对范围；给依赖边、并行波次、共享文件/资源负责人角色和汇合验收。现有编排成立时简要确认并引用原计划，只展开有必要调整的部分，不重抄完整映射或为形式新增里程碑/过程文档。只报文件不冲突、不报依赖条件的“可并行”不合格。小计划可合成一张短表。
-5. **总体结论与修订顺序**：建议状态、理由、与原状态的差异，先纠正前提/契约，再修设计、映射与编排；写清解除阻塞的可观察条件。
+5. **总体结论与修订顺序**：首行写「是否需要修改：需要 / 无需」（见下文），再写建议状态、理由、与原状态的差异，先纠正前提/契约，再修设计、映射与编排；写清解除阻塞的可观察条件。
 
 ### 就绪判断（沿用 dev-plan 的含义）
 
@@ -87,3 +87,10 @@
 - `Ready`：所审范围的实施前置均已解决，关键证据无缺口，剩余非阻塞建议不影响承诺交付。说明评审覆盖限制，不把 Ready 当作实现完成或产品上线许可。
 
 严重度和状态不是机械一一对应：同一个 P2 在某计划中可能阻塞关键外部契约，另一个 P2 只是非关键局部改进。依据影响判断，不使用总分平均掉阻塞项。
+
+### 是否需要修改
+
+以计划文本是否需要改动判定，与建议状态分开写：
+
+- **需要**：有 P0–P2 确认问题；或待核实/待决策项须写进计划（如补登记阻塞、修正前提）；或建议状态与计划自报状态不一致。
+- **无需**：只剩 P3 或无问题，且计划自报状态与建议状态一致。此时仍为 `Blocked` 表示计划已如实登记阻塞，下一步是逐项解除阻塞，不是改稿。

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

@@ -23,9 +23,11 @@
 2. 同时比较沿用现有范式和有实际收益的现代方案：能力差距、生态支持、复杂度、可维护性、迁移成本、运行成本和团队可操作性。仅因版本旧而建议升级不算问题；已有方案无法满足受支持版本、必要能力或明确约束时应指出。
 3. 涉及版本能力、弃用、支持周期、安全公告或外部服务限制等时效性事实，先读目标项目依赖/锁文件，再查官方文档、发布说明或原始论文，标记版本、查询日期和 URL。不能联网则列具体待核实项，不用记忆冒充最新结论。
 4. 审查模块边界、事实所有权、接口深度和变化局部性；新基础设施或抽象是否解决真实复杂度，删除它后是否只减少转发层。避免为假想规模过度设计，也不机械维护已不适配的现状。
+   开发对象与允许改动须能追溯到用户任务及项目职责；同仓、自有、源码或账号可访问不构成扩范围依据。外部缺口应有提供方、契约及解除条件，不替依赖方设计内部实现；用户明确纳入的跨系统任务仍须完整审查，不一概排除。
 5. 核对关键请求/任务的并发、原子性、幂等、重试、超时、租约、隔离、背压和失败恢复，按实际风险裁剪；热路径的查询/索引、缓存与新鲜性是否满足目标。
 6. 对持久化和外部契约检查新旧版本共存、迁移/回填、切换门、不可逆步骤、回滚及恢复。对外依赖核实真实能力、权限、配额和部署条件。
 7. 验证方案能否以目标仓的构建、测试和运行入口落地；风险是否有观测/验证手段。需要 spike 的未知项写“验证问题、成功判据、影响的决策、最晚完成点”，不在评审中自动实现 spike。
+8. 技术路线是否具体到实现者可直接编码：每个里程碑的改动落点、可照着改的同构实现，签名、数据结构、错误语义与页面结构有定义处。读代码、读依赖源码或小实验就能查清的未知被写成「实施时确定」「到某里程碑再冻结」，会让实施变成边做边设计，作为问题指出。
 
 交回少量关键决策的判断：`选择 | 驱动需求 | 证据与版本 | 收益/代价 | 可行性 | 必要修订或保留理由`。只是另一种同样可行的做法放非阻塞建议，不能当缺陷。
 
@@ -36,8 +38,10 @@
 `需求 R/NFR/C/A → 设计/决策 → 交付物/任务 → 里程碑 → 可观察验收`
 
 - 每条本期需求有实现与验收；每项设计/交付物有负责的任务；每个验收有设计依据。映射在账本或专门表中完整保留一份即可，需求原文和断言可引用 PRD/检查 ID，须追到定义与覆盖范围，不要求多处重复展开。排除/延期有明确去向，不能用无关测试占位。
-- 里程碑退出条件能判定局部结果，阶段收口有跨模块集成与用户主路径验证。允许同能力、同环境且无独立风险门的验收合并，核对检查覆盖、执行时点、收口负责人和前置就绪；骨架阶段不要求尚未实现的端到端路径。安全、迁移、不可逆操作、发布及用户分期门不能被合并绕过，风险不能拖到终验才发现。局部完成不等于阶段/跨期需求已验收，fixture 或构建通过不能替代真实集成、权限、业务或界面验收。
-- 完成数、最近完成、下一步、记录链接及基线一致；初稿不预填完成，进行中不计完成。已完成有本里程碑退出检查证据；可按测试组覆盖多条条件，须逐条可追溯，共同环境/基线可只写一次，不默认要求子任务文档。复用证据须有原记录及依据：相关代码、配置、依赖、输入与环境未变，否则重跑受影响检查，阶段收口仍有必要集成回归。适用 dev-plan 协议时核对逐行退出条件及里程碑记录，不机械否定历史格式。
+- 反查文件、迁移、配置、部署、故障恢复、测试替身和验收准备是否属于已确认开发范围。范围外系统的工作只作外部前置，写清责任与影响开发/集成/终验的哪一段；把它写进本方里程碑、默认排到本项目下一期，或借真实验收建设替代系统，应定位越界项及范围依据。真实集成门仍保留，不能用排除外部实现掩盖交付未闭环。
+- 开发检查是否能由 Agent 用本阶段可获得的资源执行？用户角色应有明确的知识、资料与权限约束，供 Agent 模拟；自行增设真人招募、样本人数或满意度门槛属于可执行性问题。确需真人的指标核对来源、阶段与资源前置，不默认阻塞开发；用户明确指定的开发真人门仍保留，模拟不能冒充真人数据。Agent 能操作的真实环境检查不能仅因没有真人而判受阻，也不能用 mock 替代要求的真实集成。
+- 里程碑退出条件能判定局部结果，阶段收口有跨模块集成与用户主路径验证。允许同能力、同环境且无独立风险门的验收合并，核对检查覆盖、执行时点、收口负责人和前置就绪；骨架阶段不要求尚未实现的端到端路径。安全、迁移、不可逆操作、发布及用户分期门不能被合并绕过，风险不能拖到终验才发现。局部完成不等于阶段/跨期需求已验收，fixture 或构建通过不能替代真实集成、权限、业务或界面验收。反过来，中间里程碑的退出条件排了全量测试、端到端或真实环境走查，或同一收口检查在多个里程碑复跑，会让实施反复跑全量回归，应作为编排问题指出；阶段应是多个里程碑组成的完整功能组合。
+- 完成数、最近完成、下一步、记录链接及基线一致；初稿不预填完成，进行中不计完成。已完成有本里程碑退出检查证据；可按测试组覆盖多条条件，须逐条可追溯，共同环境/基线可只写一次，不默认要求子任务文档。复用证据须有原记录及依据：只有它实际覆盖的代码、契约、配置、依赖或数据被改动才需重跑，全量回归在阶段收口跑。适用 dev-plan 协议时核对逐行退出条件及里程碑记录，不机械否定历史格式。
 - 提取有向依赖边 `前置任务 → 后置任务` 及其产物；检查循环、缺失节点、倒置、隐藏的跨系统前置和过粗的里程碑阻塞。编号不是依赖，文件分目录也不代表无依赖。
 - 区分开发、集成和终验前置，以及代码、契约、迁移、配置/权限与环境资源依赖。下游只需某个已通过必要检查的成果时，建议将依赖细化到该成果与解锁证据即可，不强制新增里程碑。稳定契约下可用 fixture 开发；无关走查或发布排练不默认阻塞开发，用户分期与风险门仍须遵守。
 

package/skills/review-prd/SKILL.md

@@ -97,6 +97,17 @@ PRD 与基线：{PRD 绝对路径及版本；代码仓根、commit/dirty、日
 
 **评审通过仅表示在已核实范围内可作为开发/测试计划的输入，不表示功能已实现、性能已实测、UI 已验证或可直接上线。** 最终聊天回复给实际报告链接、结论和关键问题/待核实项摘要。写入失败时说明「报告未落盘」并按合同保留完整内容，不能链接不存在的产物。
 
+## 5. 是否需要修改与下一步
+
+报告总体结论与最终回复都先给一行明确判定，再给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex `$apply-doc-review`、Claude Code `/apply-doc-review`），路径填实际文件。
+
+| 判定 | 条件 | 下一步 |
+| --- | --- | --- |
+| **需要修改** | 结论为「需修订」，或「需补证」且所缺事实/产品决定要写回 PRD | `apply-doc-review <本报告路径>`：核实意见、补查事实、交互确认决定后修订 PRD |
+| **无需修改** | 结论为「通过」，只剩 P3 或产品增强机会 | 按 PRD 期次出开发计划：`dev-plan <PRD 路径> P1`（PRD 未分期时省略期次；已知某期已有计划时给下一期）。想采纳 P3 或增强机会时，可选 `apply-doc-review <本报告路径>` |
+
+所缺证据只能由外部提供、PRD 本身不需改写时，写明缺什么、由谁提供，补齐后用 `review-prd <PRD 路径>` 复审。仅聊天模式没有报告文件时，说明需先落盘报告才能交给 apply-doc-review。只给出建议命令，不自行启动下一步。
+
 ## 项目状态回写
 
 若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。

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

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

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

@@ -79,7 +79,7 @@
 4. **覆盖与基线**：PRD 版本/路径、代码仓/commit/dirty、日期、实际 reviewer 分工或串行方式、四维覆盖。六个产品维度分别给结论/不适用理由；记录实际代码、测试、设计稿及浏览器证据等级与缺口，只列结论相关来源，不倾倒读文件日志。
 5. **需求追踪与分期终验**：列目标/场景/需求/验收/UAT 断链或已核对范围；检查每期独立价值、5–8 个 Milestone 预算/最多 10 个的连续性例外、关键前置、跨期终验及相互冲突的口径。建议产品交付顺序，不生成技术任务、并行波次或测试脚本。
 6. **产品增强机会**：有依据的非必要提案，写价值、场景、约束/代价及采用后需调整的需求；无则写「无」，不为创新凑数。
-7. **总体结论与修订顺序**：建议结论、阻塞范围与解除条件。先修事实/约束，再定产品语义/体验/AI，随后同步验收、UAT 和分期终验。未解决的重大未知不能藏进「通过」。
+7. **总体结论与修订顺序**：首行写「是否需要修改：需要 / 无需」（判定条件见主技能第 5 节），再写建议结论、阻塞范围与解除条件。先修事实/约束，再定产品语义/体验/AI，随后同步验收、UAT 和分期终验。未解决的重大未知不能藏进「通过」。
 
 短 PRD 可以用紧凑段落/表格承载这些内容；完整报告不是固定字数，也不是 reviewer 原始回报的拼接。结构借鉴 `review-dev-plan`，判断对象是产品需求，不沿用其实施就绪状态或技术编排要求。
 

package/skills/review-prd/references/review-lenses.md

@@ -74,6 +74,7 @@ SMAR 检查目标与需求：
 
 - 每个目标有需求承接，每个重要用户场景有预期状态与通过条件，每条完整能力有可判断的验收。UAT 应描述结果是否可用、反馈、下一步及数据变化，不只是一条提示文案。
 - 成功与本产品相关的空、拒绝、冲突、取消、失败/恢复和 AI 不确定/降级场景有清晰结果。不能到测试计划阶段才决定产品状态，也不能把造数、脚本、探针、故障注入当 UAT 内容。
+- 开发验收是否适配 AI Agent coding？角色与知识前提不等于招募真人；无用户或已确认约束依据的真人样本数/满意度开发门槛应指出。确需真人的指标按来源单列公测/上线后验证，保留用户明确指定的开发真人门，不接受角色模拟冒充真人数据。
 - 没有 TC、没有 SPMS key、章节不同本身不算缺陷。真实 key 不可伪造；缺少验收语义才是问题。代码/设计内部断言若无法表达外部结果，要求改为业务边界，不要求 PRD 拟写测试过程。
 - 每期有独立用户价值、范围与出口判据，不按前后端技术栈切期。终局需求不因交付节奏被删小，非目标不充当延期列表；已明确的其他 PRD 分工可作为范围去向。
 - 每期开发计划尽量 5–8 个 Milestone；连续性例外 9–10 个说明理由，最多 10 个；小范围可以更少，不凑数。这里只检查规模预算，详细任务和准确拆解由 dev-plan 核实，超出则反馈拆期。

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

@@ -1,6 +1,6 @@
 ---
 name: review-prd-dev-gaps
-argument-hint: "<PRD> <已完成开发计划...> [上轮报告] [复审/完整核查] [G-ID/范围] [仅报告] [报告路径]"
+argument-hint: "<已完成开发计划...> [PRD] [上轮报告] [复审/完整核查] [G-ID/范围] [仅报告] [报告路径]"
 description: 用于开发完成后的 PRD 覆盖核查；不用于 PRD 质量、计划设计或单次 diff 评审。对照已完成计划、记录和实现，区分遗漏与变更，交互裁定差异，必要时生成 gaps plan。
 ---
 
@@ -12,7 +12,7 @@ description: 用于开发完成后的 PRD 覆盖核查；不用于 PRD 质量、
 
 ## 边界
 
-- 输入为 PRD、已完成开发计划及其引用的完成记录；代码仓、测试、运行证据和历史决策用于核实。目标无法唯一确定时询问文档/仓库位置，先做不依赖该信息的调查，不擅自选择相邻文档。
+- 输入为 PRD、已完成开发计划及其引用的完成记录；代码仓、测试、运行证据和历史决策用于核实。只给计划时，从计划顶部「需求来源」定位 PRD 与期次（`P1` 即第 1 期），核查范围为 PRD 分期中落在该期的需求与验收，跨期需求只核对本期部分并保留终验期去向；用户另给范围时从其要求。计划没有需求来源且未给 PRD 时询问。目标无法唯一确定时询问文档/仓库位置，先做不依赖该信息的调查，不擅自选择相邻文档。
 - 默认写差异报告、新 gaps plan 及已启用台账的事实索引（见文末）。原 PRD、原计划、完成记录和代码保持只读；文档同步也列为 follow-up，不自动修改历史完成事实。不自动实施、创建 issue、发布或发送评论。
 - 只核对 PRD 及已确认变更承诺的范围，不新增产品机会，不设问题数量或 top-N 截断。明确不在本期的需求保留追踪去向，不当成本期遗漏；未获确认的删减/延期不能算范围外。
 - 参考 `gen-specs-as-issues` 的文档对照实际行为、用户旅程和依赖分析思路，不继承其问题配额、评分公式或 issue 创建流程；运行时不依赖该参考技能。
@@ -30,7 +30,7 @@ description: 用于开发完成后的 PRD 覆盖核查；不用于 PRD 质量、
 用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
 
 - 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
-- 读取上轮 G-ID、D-ID、原计划及已有关联 gaps plan 和完成记录；沿用仍有效的用户决定。逐项核对需求是否补齐及直接受影响的用户路径，不因计划自报完成关闭缺口。复审模式的覆盖账本标明本次范围，其余保留“本轮未复核”，不能冒称全 PRD 已覆盖。
+- 读取上轮 G-ID、D-ID、原计划及已有关联 gaps plan 和完成记录；沿用仍有效的用户决定。只给 gaps plan 时，沿其需求来源找到原计划与上轮差异报告，一并核对。逐项核对需求是否补齐及直接受影响的用户路径，不因计划自报完成关闭缺口。复审模式的覆盖账本标明本次范围，其余保留“本轮未复核”，不能冒称全 PRD 已覆盖。
 - 先查已有 gaps plan 是否承接剩余事项；已承接则链接原任务及真实进度，不重复创建计划。只有尚未承接且范围已确定的新增 follow-up 才进入第 5 节；“仅报告/只复核”只交付报告与后续建议，不调用 dev-plan 创建或修订计划。
 - 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
 
@@ -87,7 +87,7 @@ $review-prd-dev-gaps docs/PRD-login.md goal/LOGIN.md goal/LOGIN-gaps.md，对照
 - 已满足、无后续动作的 B、明确豁免或已延期到别期的事项不进入本次实施范围；报告保留理由、去向和重新评估条件。全部无 follow-up 时明确写「无需 gaps plan」，不创建空计划。
 - 先按 G-ID、需求及实际范围核对已有 gaps plan；已承接事项链接原任务，不重复建计划。仍有未承接的已确定增量且用户未限定仅报告时，**实际定位并读取可用的 `dev-plan/SKILL.md`，按其写计划流程、骨架和校验生成独立 gaps plan**；不止建议用户以后调用，也不在本技能复制一套开发计划模板。缺少该技能时查找可用安装位置；仍找不到则保留报告和交接清单，说明计划生成受阻，不能声称已创建。
 - 交给 `dev-plan` 的输入：PRD、原计划及相关记录路径，差异报告、代码基线，选定 G-ID 和 D-ID，已确定目标与验收、排除/延期项、相关代码证据和依赖。原 PRD 提供来源，用户确认的变更提供新目标，当前代码提供起点；不能让下游再次按旧 PRD 推翻已确认决定。
-- 使用 `<原计划名>-gaps` 作为默认代号，输出目录、重名处理和最终状态遵守 `dev-plan`。保留 PRD 需求 ID，并追踪 `需求 → G-ID/D-ID → gaps 任务/里程碑 → 验收`；只规划增量，不重做已完成里程碑，不复制旧计划的完成记录，初始化新计划未开始的进度。
+- 使用 `<原计划名>-gaps` 作为默认代号，输出目录、重名处理和最终状态遵守 `dev-plan`。gaps plan 的需求来源写同一 PRD 与期次，并注明补齐的原计划，使其代码验收通过后可再次核查。保留 PRD 需求 ID，并追踪 `需求 → G-ID/D-ID → gaps 任务/里程碑 → 验收`；只规划增量，不重做已完成里程碑，不复制旧计划的完成记录，初始化新计划未开始的进度。
 - 未决 C 不得作为已选方案进入计划。若仍在等回答，先保存报告；独立且已确定的 follow-up 可先成独立范围的计划，显式排除待决项。未决项影响该计划范围或关键依赖时按 `dev-plan` 标 `Blocked`，不能用假设绕过；不得把部分计划说成全部差异已处理。
 - 计划生成后回读，检查范围、决策、验收与报告一致，并在报告中回填实际路径、状态和 G-ID 去向。默认到计划交付为止，不开始执行 gaps plan。
 
@@ -97,6 +97,14 @@ $review-prd-dev-gaps docs/PRD-login.md goal/LOGIN.md goal/LOGIN-gaps.md，对照
 
 最终回复给报告链接、三类差异数量、待核实/待决数量，以及 gaps plan 的实际链接与状态（或无需生成/受阻原因）。报告落盘、用户决策、计划生成分别说明完成情况；有未决/缺证时不宣称整份 PRD 已完整交付。
 
+结尾给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex `$review-dev-plan`、Claude Code `/review-dev-plan`），路径填实际文件。
+
+- 生成了 gaps plan：`review-dev-plan <gaps 计划路径>`，之后与普通计划同一回路：评审处置、解除阻塞、`/goal` 开发、代码评审验收，通过后可再次核查本期覆盖。
+- 无需 gaps plan 且没有待决或缺证：说明本期 PRD 覆盖核查完成，跨期需求的终验期仍以 PRD 为准。
+- 尚有待决或缺证：列出待用户决定的问题或补证方式，处理后再次 `review-prd-dev-gaps <计划路径>`。
+
+只给出建议命令，不自行开始执行 gaps plan。
+
 ## 项目状态回写
 
 若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。

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

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

package/skills/review-ui/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: review-ui
+argument-hint: "[开发计划] [页面URL/路由] [设计稿/目标图] [上轮报告] [复审/重建基线] [单元/范围] [门槛分] [报告路径]"
+description: 用于界面实现后的 UI/UX 验收或修复复审；不用于代码 diff 评审、直接修复或从零设计。只认运行中界面的实拍截图与实测，不凭代码推断效果；由独立评审打分列差距，判定是否通过。
+---
+
+# review-ui · UI/UX 验收评审
+
+判断实现出来的界面是否达到预期，并给出一份清单：另一位 agent 照单修完，下一轮分数应明显提高。本技能与 `apply-ui-review` 组成验收循环：每次调用评一轮，修复后再评，直到通过、停滞后交用户裁定，或用户明确放过。
+
+**每轮由全新上下文的独立评审对照目标打分。主 agent 只负责采集、复核和裁定，不给自己的修复打分。** 循环的状态都在落盘文件里：目标包、逐轮截图、评审原始结论、报告和修复记录。手动交替调用和用 goal 自动推进，都按同一规则续接。
+
+**只认真实效果。** 分数、差距和判定只能来自三种证据：本轮在真实运行的产品上实拍的截图、实际执行过的操作、在页面上实测的结果。代码、diff、计划、设计意图，以及「按代码应该会这样」的推断，只能用来找入口、定位问题，不能用来打分、开差距、关差距或判通过。拿不到真实效果的单元不打分，判需补证：宁可不评，也不能想象。
+
+**默认交付**：首轮建立目标包；每轮的截图、评审原始结论和完整报告落盘并回读。聊天先给验收判定，再给分数轨迹、关键差距、截图位置和下一步命令。产品代码、计划和历史报告只读，不修复、不提交、不改进度。
+
+`references/` 相对本文件解析。目标仓的启动方式、账号、设计规范和截图工具在运行时发现。语言跟随用户。
+
+## 适用边界
+
+- 适用于有可运行界面的验收：计划实施并通过代码评审后可选的 UI 验收、修复后的复审，以及用户给出页面与目标图或规范的单次验收。
+- 不适用于：代码缺陷评审用 `review-code`；修复差距用 `apply-ui-review`；找视觉方向用 `design-reference`；交互方案选型用 `ui-pattern-research`；维护 DESIGN.md 用 `design-md`。
+- 拿不到真实效果时（没有可用的渲染或截图工具、应用起不来、状态到达不了），按上面的规则判需补证，说明缺什么、怎么补。
+
+## 循环模式与能力探测
+
+先确定本循环的前缀，检查 `<前缀>.ui-review.json`、已有报告和安装回执。已有纯 Markdown 历史而无 managed 索引时继续人工流程，必须显式 import 才接管。全新无索引、无旧循环历史且用户已要求 UI 验收时，先按下述协议探测；真实 engine 与 review verbs 匹配后可 `review begin` 建立 managed 循环，缺 CLI 或能力不匹配时走人工流程。没有 CLI 不妨碍读取原文、采集真实界面和人工落盘；没有机器索引就不能假称已接管。
+
+已有 managed 索引时，先按 [Phoenix 评审协议](references/phoenix-review.md) 核对固定版本 engine 的身份与实际支持的 review 协议。缺失、不匹配、未来 schema 或索引损坏时只读历史，可收集未登记素材；不计分、不裁定、不写处置、计数或报告生成区，也不新建循环来绕过原状态。说明恢复匹配 engine 的方法，恢复后续接原轮次与 revision。
+
+匹配时由 `review begin` 分配轮次并冻结目标与矩阵，后续依次登记采集、读取白名单 packet、登记评审原文、裁定与回读。JSON 输入按实际 `review --help` 与 `review schema --json` 返回的 typed examples 构造，不猜字段；样例不是证据，身份、hash 和 revision 必须取真实操作与材料。旧 Markdown 只有经显式 `review import` 才进入 managed 循环；历史不明的尝试或重构次数不能当作零。
+
+## 1. 锚定对象与目标包
+
+1. 读取适用的仓库规则。给了开发计划时，读计划的前端与交互、真实环境与 UI 验证、里程碑验收，再沿「需求来源」读 PRD 中的界面需求与 UAT。同时读项目 DESIGN.md 或主题规范，以及计划或 PRD 链接的设计稿。只给 URL 或路由加目标图时，按单次验收处理。
+2. 按 [报告合同](references/report-contract.md) 的命名规则确定前缀和轮次。人工循环取已有最大轮次；managed 循环读索引，未结束轮次续接原 round/revision，不自行加一。已有本循环的报告时，本轮为复审；每个单元的「上一轮」是最近一次覆盖它且有评审结论的轮次；覆盖了却没有任何评审结论（如全部缺证封存）的轮次不算。
+3. 按 [目标包与采集](references/target-and-capture.md) 定位或建立目标包，并计算目标指纹。指纹与上一轮 `capture.md` 记录的不同，说明期望或目标图变了，本轮就是**重建基线**：历史最佳分、停滞判定和重构记录都从本轮重新开始。只改「采集」节不影响指纹。
+4. 目标包建立后，本技能不改写其中的期望，只能修改「采集」节并记入变更记录。目标图与规范互相矛盾时，列为待裁定事项；某单元既没有目标图也没有规范时，该单元需补证。其他单元照常评审。
+
+## 2. 采集本轮截图
+
+1. 按目标包启动或连接被测环境，记录被测版本（HEAD、未提交改动指纹或构建号）和访问地址，并确认运行的是当前代码而不是旧构建。为评审临时启动的服务放在后台运行，记下停止方式，结束前停掉。只用测试账号和种子数据，不对真实业务数据写入或做破坏性操作。
+2. 每轮采集目标包的**全部**格子（单元 × 状态 × 视口 × 主题），这样才能发现回归。用户限定范围时只采该范围，其余标「本轮未复核」。每轮在相同条件下重拍，不挑好看的角度或数据。
+3. 每张截图都必须本轮在真实产品上实拍，要求见 [目标包与采集](references/target-and-capture.md) 的「真实性」。设计稿、旧截图、为评审写的模拟页面等不合要求的图，一律当作没采到。
+4. 交互单元按步骤实际操作，每步动作之后拍关键帧，包括键盘走查时的焦点帧。操作记录只写实际执行的动作和截图里看到的结果，不写「应该会」「预期会」之类的推断。采集期间顺带保存控制台日志和失败请求，留到评审之后再分析。
+5. 状态到达不了时，先找项目已有的造数、mock 或路由拦截手段。仍采集不到的格子写明原因，不用相近状态冒充。
+6. 按报告合同保存被测版本、目标指纹、采集条件、每张图对应的格子和出处，以及没采到的格子。人工循环写 `capture.md`；managed 循环用 `review capture add` 登记并回读生成的清单，补采追加 attempt，不覆盖原图或旧记录。
+
+## 3. 独立评审
+
+按 [独立评审](references/judge.md) 派发和复核：
+
+- **每轮派一个全新上下文的 subagent 当评审**，只读，不再派生。评审只拿到三样东西：目标包；本轮截图、`capture.md` 与交互记录；每个单元上一轮的截图和 `judge.md`（只含评审自己给的分和差距）。
+- **不给评审的东西**：代码、diff、提交说明、修复记录、修复者自述、完整报告、机器检查结果和门槛分。并要求评审只打开所列材料，免得被「已经修了」带偏，也免得朝门槛凑分。
+- managed 循环用 `review judge-pack` 的白名单材料派发；不沿材料内链接打开被排除的文件。packet 的 hash 绑定本批材料，确认评审沿用同一批材料；白名单是信息边界，不冒充宿主的文件权限沙箱。
+- 格子多时按单元分组并行派发。新差距先用临时编号，由主 agent 合并后统一编号。评审报告看不出的格子，主 agent 补采后再派一位全新评审重评涉及的单元，取较低分。
+- 派不出 subagent，或评审打不开图片时：
+  - 当前对话没参与这个界面的实现或修复：主 agent 可以自己评审。评审前只读目标包、本轮和上一轮的截图、`capture.md` 和 `judge.md`；先评审并保存 `judge.md`，再做第 4 节的事；报告注明「单上下文评审」。
+  - 当前对话参与过：不在本对话打分，给出在新对话运行本技能的命令。
+- 主 agent 不改分、不删差距、不改门槛项，也不因争议换评审重评。认为评审看错时，只在该差距下附核对说明，交给修复方核实，下一轮由评审复核。
+- 本轮将判通过、但最低单元分严格低于「门槛 + 0.5」时，用同一批材料再派一位全新评审确认；恰好等于时不强制。每个单元选总分较低的那位评审的一整组四维分与理由，差距取全部评审的并集；不逐维拼成一个不存在的评分。
+
+## 4. 裁定与落盘
+
+1. 保存各位评审原文及本轮合并的 `judge.md`；managed 循环还须用 `review judge add` 登记原文与忠实的结构化结果并回读。此后再做以下几件事：
+   - 做机器检查，全部在运行中的页面上执行：分析采集时保存的日志，在页面里实测溢出，注入可访问性扫描，用真实按键做键盘走查。从代码或样式表推断出的问题不算检查结果，只能提示去哪里补拍或实测；
+   - 读上轮完整报告和各轮修复记录。修复记录在计划记录目录里含「UI 验收修复」节的那份；没有计划时，是 `<前缀>.ui-review.applied.md`；
+   - 确定门槛：用户本次指定的优先，其次沿用上轮报告记录的，都没有则默认 8/10。
+2. 按报告合同完成裁定：
+   - 由主 agent 重新检查上轮的机器检查差距和主 agent 核实的差距；
+   - 计算本轮分数、门槛项、待裁定事项和停滞状态；
+   - 得出验收判定。
+3. 人工循环按报告合同写报告；managed 循环用 `review finalize` 以当前 revision 提交裁定，不手写生成区。返回 `confirmation_required` 时本轮仍是草稿，先完成确认评审再裁定；操作退出 0 本身不表示验收通过。写完回读状态、报告和链接，核对判定、分数与编号映射。写入失败时如实说明未落盘，并在聊天中交付已核实的内容。
+
+## 5. 验收判定与下一步
+
+最终回复先给一行验收判定（定义见报告合同），再给分数轨迹、最低分单元及主要差距、最新截图位置，最后给可直接复制的下一步命令。命令按当前客户端的技能调用写法（如 Codex `$apply-ui-review`、Claude Code `/apply-ui-review`），路径填实际文件。
+
+首轮刚建立目标包时，列出期望的来源和假设，请用户确认；用户修改期望后，下一轮按重建基线评审。
+
+| 验收判定 | 下一步 |
+| --- | --- |
+| 需要修改 | `apply-ui-review <本报告路径>`，修复后再用本技能复审。带「停滞预警」时，说明是全局重构，还是重构哪个单元。带「待裁定」时，同时列出这些事项请用户决定；修复方先处理其余差距 |
+| 通过验收 / 用户豁免通过 | 给出最新截图，问用户是否继续打磨：要打磨就 `apply-ui-review <本报告路径>` 处理剩余差距，再复审。不打磨时，如果本轮循环的 UI 修复改了代码（登记为「UI修复」的提交或未提交改动），先 `review-code <计划路径>` 复审这些改动；之后计划来自 PRD 的可选 `review-prd-dev-gaps <计划路径>` |
+| 需用户裁定 | 列出停滞或待裁定的事项、已经试过的做法，以及目标与当前截图的对照，请用户从下面三个选项中选择 |
+| 需补证 | 列出缺少的环境、账号、数据、工具或目标，以及获取方式；补齐后再 `review-ui <计划路径或原范围>`。已评单元的差距可以先 `apply-ui-review <本报告路径>` |
+
+需用户裁定时的三个选项：
+
+1. 接受整体现状，记为豁免通过；
+2. 接受某处偏差或修改期望，由用户确认后改目标包，下一轮重建基线；
+3. 提供素材或方向，然后执行 `apply-ui-review <本报告路径>`。
+
+- 用户明确表示接受当前的整体界面时，按报告合同追加豁免记录并回读。豁免不能写成已解决。
+- 只给建议命令，不自行启动修复、代码复审或差异核查。
+
+调用示例：
+
+```text
+使用 $review-ui goal/LOGIN.md
+使用 $review-ui goal/LOGIN.md，设计稿在 design/login/，门槛 8.5 分。
+使用 $review-ui 验收 http://localhost:5173/orders，目标图 docs/design/orders.png。
+使用 $review-ui goal/LOGIN.md，只复查 U2。
+```
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存及 managed 能力异常时的只读边界优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+每轮实际评审都登记独立的评审 ID，写明被测版本、目标指纹、范围、判定、分数和报告路径；复审关联前轮。协议的 `review_type` 没有 UI 类型时，登记为 `other`，并在摘要注明「UI 验收评审」。通过验收不能登记为已合并、已发布或产品终验通过。

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "UI/UX 验收评审"
+  short_description: "只认运行中界面的实拍截图，由独立评审打分并列出可执行差距，判定 UI 验收是否通过"
+  default_prompt: "使用 $review-ui 对指定界面做 UI/UX 验收。先识别循环：新无历史且真实能力匹配时可 begin managed；已有人工历史须显式 import。已有 managed 索引时核对固定 engine 与实际协议，不匹配就只读并说明恢复方法，不猜 JSON 字段。按目标矩阵实拍真实界面，派全新上下文独立评审，保留原文并按合同确认、合并和裁定；managed 操作由 engine 登记与投影，人工流程照常落盘。回读后汇报实际判定、分数、差距和下一步命令。"