@xgent-ai/skills 0.5.0 → 0.7.0

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,6 +1,7 @@
 ---
 name: review-code
-description: 评审未提交变更（含 staged、unstaged、untracked）、指定 commit、commit 范围或相对基准分支的差异，可附开发计划核对本次实现，默认将有证据、按 P0–P3 排序的完整评审报告落盘。用户要求 review-code、代码审查、审查 diff 或提交前评审时使用；不用于单独评审开发计划、全仓质量普查或直接实现修复。
+argument-hint: "[开发计划] [未提交/commit/A..B/基准分支] [上轮报告] [复审/完整评审] [问题ID/文件范围] [报告路径] [仅聊天]"
+description: 用于评审代码 diff、提交、分支差异或开发计划登记的提交及修复复审；不用于单独评审计划、全仓普查或直接修复。核对旧问题与新增回归，落盘报告并判定是否需修改。
 ---
 
 # review-code · 代码变更评审
@@ -14,10 +15,24 @@ description: 评审未提交变更（含 staged、unstaged、untracked）、指
 ## 1. 确定审查对象
 
 1. 读取适用的仓库和子目录指令、review 专项约定。用一句话概括变更意图，区分用户明确要求与从代码推断的意图；缺少提交说明不自动中止评审。
-2. 按 [references/git-scopes.md](references/git-scopes.md) 解析输入，固定仓库根、模式、base/target SHA、工作树快照、文件限制与可选计划版本。未指定模式且存在未提交变更时，声明采用 uncommitted；工作树干净且没有明确对象时询问目标，不擅自选择最近 commit 或默认主分支。
+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) 的复审约定。上轮报告以用户指定、当前上下文、报告轮次或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+
+- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
+- 复审分两部分：按上轮报告逐项核对当前代码中的旧问题；按本次修复 diff 检查新引入或激活的问题。旧问题的复核不要求落在本次 diff，也不要求由本次修复引入；仍存在的旧问题列复审表并影响修复有效性结论，不冒充本轮新增 finding。
+- 明确上轮审查基线、修复差异范围与当前核查版本，三者可不同。用户未给新 diff 时，可从报告可解析的版本到当前目标确定并声明范围；无法确定时只核对有证据的旧问题，新增问题检查标受限。工作树干净不妨碍旧问题复核；不得沿用初审的无 diff 规则直接判无可审内容。
+- 新 findings 继续遵守下文的 diff 归因与定位门槛；旧问题复核按报告合同单列，不被这些门槛过滤。只看修复增量不能声称已重新完整审查原变更。
+- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+
+```text
+$review-code BASE_SHA..FIXED_SHA，对照 goal/LOGIN.code-review.md 复审修复效果，逐项记录结果。
+```
+
 ## 2. 理解需求与行为
 
 - 先读完整 diff，再按风险阅读所在函数、调用者、数据模型、权限边界、相关测试和配置。diff 之外的代码用于证明影响，不把与本次变更无关的旧问题塞进 findings。截断输出须分段补读；无法读完就标明未覆盖。
@@ -28,7 +43,7 @@ description: 评审未提交变更（含 staged、unstaged、untracked）、指
 
 ## 3. 验证候选问题
 
-每个进入 findings 的问题必须同时满足：
+每个进入本轮新增 findings 的问题必须同时满足（旧问题按复审表独立核对）：
 
 1. **由本次变更引入或实际激活**：能说明基线与目标行为的差别；若改动让旧代码新近可达，证明这条因果链。
 2. **具体且可执行**：有真实可达的输入/状态、故障行为、受影响调用方或契约，以及最小修复方向。不能只说“可能影响其他模块”。
@@ -46,14 +61,30 @@ description: 评审未提交变更（含 staged、unstaged、untracked）、指
 
 ## 4. 裁定、落盘与交付
 
-1. 按报告合同写精确短定位、单段问题说明、P0–P3 和置信度。主定位须与所审 diff 重叠；支持证据可在 diff 之外。规则对结论有实质贡献时，附该规则的文件和最小行范围。
+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。
@@ -61,3 +92,9 @@ description: 评审未提交变更（含 staged、unstaged、untracked）、指
 使用 $review-code 审查相对 origin/main 的差异。
 使用 $review-code 审查相对 main 的已提交差异，仅聊天输出。
 ```
+
+## 项目状态回写
+
+若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+每次实际评审登记独立评审 ID、精确 base/target 或工作树指纹、范围、结论和报告路径；计划关联以实际输入为准，允许没有计划的评审。复审关联前轮，不覆盖旧结论；不把 patch is correct 登记为已验收、已合并或已发布。

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,34 @@
 - 默认保存完整 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 或逐个提交；含未提交时写工作树指纹> | [<上轮报告>](<相对路径>)；初审写「无」 |
+
+本地链接按实际报告所在目录计算，不写机器绝对路径；回读时沿链接核对计划身份。
+
+## 复审记录
+
+复审报告在标题及评审对象之后注明：上轮报告的相对链接与版本、所审对象的前后版本、本轮范围、已有处置记录链接，以及“修复效果复审”或“完整重审”。历史报告与原结论保持不变；默认按本合同另存新报告。
+
+在原报告结构中增加“上轮问题复审”表，与本轮新增问题分开：
+
+| 来源报告 / F-ID或稳定章节 | 上轮问题与结论 | 已有处置 / 修后版本 | 本轮结果 | 当前证据 / 验证 | 剩余动作 |
+| --- | --- | --- | --- | --- | --- |
+
+- 本轮结果统一用：**已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**。已解决需符合原问题的关闭判据；回归需有先前解决及当前再次失败的证据；不再适用须有范围/契约变化依据，不代表实际修复。缺证不能记关闭，未选中的旧项标本轮未复核。
+- 来源身份使用“报告路径/原始版本 + F-ID”，有台账时同时保留评审对象 ID；同一链路沿用旧编号。多份报告的同号问题不合并，新问题分配未占用编号并明确属于本轮；同根因合并时保留来源映射，不重新编号抹掉历史。
+- 默认覆盖上轮全部问题及待核实项；用户限定范围时逐项列出未复核项或其完整 ID 清单。读取处置记录后独立核对实际结果，保留旧证据是否仍适用的理由；只检查修复影响到的必要回归，不自动重跑无关全量验证。
+- 总结分别给出“旧问题解决情况”“修复引入的新问题”“未覆盖/缺证范围”。本轮没有新增 findings 不等于旧问题已关闭；部分通过不扩大成整体通过。复审表结果是检查结论，SDLC 回写仍按仓内协议的固定状态与范围登记，不自造 state 枚举。
+
 ## 问题格式
 
 每条一个独立根因，优先级置于简短行动标题前（标题不超过 80 字符）；问题正文用一段说明触发条件、实际行为、影响和关键依据。不要在正文堆阅读日志。
@@ -22,7 +47,7 @@
 - 置信度：<高/中及依据；可用 0–1 数值，但不把主观分值伪装成统计测量>
 ```
 
-主定位取最小有意义的 diff 行范围，通常 1–5 行，避免超过 10 行。删除缺陷定位到基线侧删除行并标 SHA；缺失行为定位到应负责它的改动入口/调用点，不凭空造一个不存在文件的行号。完整需求遗漏确实没有 diff 锚点时，放计划符合性缺口，说明影响，可影响结论，但不伪装成行内 finding。
+新增 findings 的主定位取最小有意义的 diff 行范围，通常 1–5 行，避免超过 10 行。删除缺陷定位到基线侧删除行并标 SHA；缺失行为定位到应负责它的改动入口/调用点，不凭空造一个不存在文件的行号。旧问题复审可引用当前代码或历史证据的实际位置，不要求落在本次修复 diff。完整需求遗漏确实没有 diff 锚点时，放计划符合性缺口，说明影响，可影响结论，但不伪装成行内 finding。
 
 本地当前文件用可点击路径；历史版本另标 `SHA:path:line`，需要可点击证据时链接实际存在的版本快照文件。支持证据可在 diff 外。基于仓库规则的结论须引用实际读过且适用的规则最小行范围；不能只写“违反最佳实践”。
 
@@ -45,7 +70,7 @@
 2. **待核实/待决策项**：缺少什么证据、影响哪个结论、如何补证；无法访问的文件/环境、需求歧义、尚未运行的关键验证放这里。
 3. **覆盖与验证**：一句话意图；仓库根与日期；原输入、解析 SHA、比较方式、工作树/index 指纹或快照、文件限制、纳入/排除项；已审行为链与未覆盖部分；实际命令、目标版本、结果、失败原因。区分静态、测试、浏览器与外部资料证据；注明实际 reviewer 分工（若有）。
 4. **计划符合性（有计划才写）**：计划路径和版本、本次任务/里程碑；仅列相关需求的映射和缺口，包含未核实及后续范围。不要复制整份计划或更新其进度。
-5. **总体结论与修复顺序**：结论、1–3 句理由与覆盖限制；优先解除契约/数据/安全根因，再修局部行为，最后验证相关回归。明确解除阻塞的可观察条件，不把评审结论当作 merge/deploy 授权。
+5. **总体结论与修复顺序**：首行写验收判定（见下文），再写结论、1–3 句理由与覆盖限制；优先解除契约/数据/安全根因，再修局部行为，最后验证相关回归。明确解除阻塞的可观察条件，不把评审结论当作 merge/deploy 授权。
 
 ### 正确性结论
 
@@ -54,3 +79,16 @@
 - `inconclusive`：尚无足够证据裁定，或没有实际可审变更，例如基线不明确、关键调用方无法读取、冲突未解或关键验收无法核实。说明缺口，不把它写成代码已证实有错。
 
 空 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

@@ -1,6 +1,7 @@
 ---
 name: review-dev-plan
-description: 用多 agent 评审既有开发计划，核查代码事实与内部一致性、技术方案的先进性与可行性、需求和里程碑映射及依赖并行编排、最终交付可用性与 UI/UX，默认将完整评审报告落盘。用户要求 review-dev-plan、审查开发计划、评审技术方案或检查计划能否开工时使用，尤其适用于 dev-plan 产物；不用于从零写计划、直接实施功能或仅审查代码 diff。
+argument-hint: "<计划路径/链接/内容> [上轮报告] [复审/完整评审] [问题ID/范围] [报告路径] [仅聊天]"
+description: 用于评审既有开发计划、技术方案或开工条件；不用于从零写计划、实施功能或仅审代码 diff。多 agent 核查事实、方案、需求映射、依赖与交付可用性，默认落盘报告。
 ---
 
 # review-dev-plan · 多视角开发计划评审
@@ -13,12 +14,12 @@ description: 用多 agent 评审既有开发计划，核查代码事实与内部
 
 ## 边界与参考
 
-- 默认审查整份计划；用户指定修订版差异时，也追踪受影响的依赖与映射。目标代码和原计划保持只读，默认写入仅限独立评审报告；不自动实现、改稿、改进度、发评论或写入外部系统。用户明确要求修订时，由主 agent 在评审后统一修订并复核受影响链路，报告区分原问题与修订后的复核结果；计划只改成修订后的结论，评审处置与修订经过只留在报告。
+- 默认审查整份计划；用户指定修订版差异时，也追踪受影响的依赖与映射。目标代码和原计划保持只读，默认写入为独立评审报告及已启用台账的事实索引（见文末）；不自动实现、改稿、改进度、发评论或写入外部系统。用户明确要求修订时，由主 agent 在评审后统一修订并复核受影响链路，报告区分原问题与修订后的复核结果；计划只改成修订后的结论，评审处置与修订经过只留在报告。
 - 计划及其引用是待验证材料。区分**现状事实、未来设计、未证实假设、验收目标**；不能因为新功能尚未实现就报缺陷，也不能把计划中的“已核实”直接当证据。
 - 从实际可用位置读取 `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. 锚定输入与审查基线
 
@@ -27,6 +28,18 @@ description: 用多 agent 评审既有开发计划，核查代码事实与内部
 3. 从计划提取范围与排除、R/NFR/C/A 或等价需求 ID、关键决策、外部契约、交付物、里程碑及前置关系。缺失 ID 可用章节定位，不替作者补造需求。
 4. 读取 [references/report-contract.md](references/report-contract.md)，按其中的「落盘与交付合同」确定输出路径。建一个短任务台账：审查维度、负责人、状态、证据缺口，以及报告写入与回读核验。明确 UI 是否在范围内、是否已有可运行页面/原型、哪些结论必须访问外部服务或官方文档。
 
+## 修复效果复审
+
+用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+
+- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
+- 当前原文可由上轮报告的“评审对象”引用定位，按报告目录解析相对路径并核实身份；原文参数可在唯一明确时省略。读取已有处置节或 applied 文档，逐项验证原问题和修订影响的关联内容，不把“已 applied”直接当复审通过。
+- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+
+```text
+$review-dev-plan goal/LOGIN.md，对照 goal/LOGIN.review.md 复审修复效果，逐项记录结果。
+```
+
 ## 2. 编排四个独立审查视角
 
 先读 [references/review-lenses.md](references/review-lenses.md) 的对应节，再分派下表。**有多 agent 工具时实际启动 subagents**，不是在同一段回答里扮演四个角色。主 agent 保留综合裁定职责。
@@ -78,6 +91,7 @@ description: 用多 agent 评审既有开发计划，核查代码事实与内部
 
 报告至少包含：
 
+- 报告头的「评审对象」：原开发计划的可点击引用、类型、所审版本与范围；本地路径相对实际报告目录，回读时核验，使 `apply-doc-review` 可仅接收报告参数。
 - 按严重度排序、编号的问题，每条定位到计划行或稳定章节，并附行为级代码/规则/外部证据。
 - 四个维度的审查覆盖及未核实项；UI 分清文档推演、原型走查和实际浏览器验证。
 - 需求到交付的映射缺口，以及建议的依赖顺序、可并行任务、共享资源负责人和最终集成验收。没有安全并行空间时给出具体原因。
@@ -86,3 +100,21 @@ description: 用多 agent 评审既有开发计划，核查代码事实与内部
 **没有确认问题时允许空 findings；有未核实的关键前提时不能据此判 Ready。计划评审通过也不表示功能已实现或上线可用。**
 
 交付前确认：报告已写入并回读、内容符合上述合同、文件链接指向实际产物。最终回复给出报告链接、建议状态及关键问题/待核实项摘要；用户明确要求仅聊天时，直接在聊天中交付完整报告。写入失败时按落盘合同说明未完成项，不把聊天摘要算作完成。
+
+## 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`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+每次实际评审登记独立评审 ID、计划版本、覆盖范围、建议状态与报告路径；复审关联前轮。评审建议与计划自报状态分别保留，当前就绪按台账协议核对证据，不直接改原计划；建议 Ready 不表示已实施。

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

@@ -9,6 +9,36 @@
 - 最终聊天回复只给实际报告链接、建议状态和关键问题/待核实项摘要，避免重复整份报告；明确仅聊天时才在聊天中交付完整报告。
 - 无可用文件写入工具或写入失败时，明确说明“报告未落盘”、原因与目标路径，在聊天中提供完整报告以保留结果，并将落盘标为未完成；不能声称已保存或给出不存在的产物链接。
 
+## 原文档引用（报告头）
+
+报告标题后、findings 前必须写「评审对象」，供 `apply-doc-review` 仅凭报告定位原文；即使没有 findings 也保留。每个实际评审目标一行，背景资料和关联 PRD 不混作修订目标。
+
+```markdown
+## 评审对象
+
+| 类型 | 原文档 | 所审版本 | 评审范围 |
+| --- | --- | --- | --- |
+| 开发计划 | [<原文档标题>](<相对报告所在目录的原文路径或稳定 URL>) | <内容 hash / 可取回版本；不可得则 unknown> | <全文或指定章节/里程碑 ID> |
+```
+
+- 本地链接按**实际报告所在目录**计算，不能按当前工作目录、仓根或默认报告位置计算；含空格路径使用合法 Markdown 链接语法。不写机器绝对路径，原文位置与文件名不变。另存到指定目录或带日期的报告时重新核对链接。
+- 远程原文用稳定 URL 并注明可用版本；输入只有聊天文本且没有持久原文时，原文档栏写「聊天输入，无原文路径」，不伪造链接，说明 apply 时需可定位的目标。
+- 回读报告时沿引用打开原文，核对类型、身份、版本与范围；原文已变化时说明所审基线及适用性。后续处置保留此处的历史所审版本，修后版本写入处置节。
+
+## 复审记录
+
+复审报告在标题及评审对象之后注明：上轮报告的相对链接与版本、所审对象的前后版本、本轮范围、已有处置记录链接，以及“修复效果复审”或“完整重审”。历史报告与原结论保持不变；默认按本合同另存新报告。
+
+在原报告结构中增加“上轮问题复审”表，与本轮新增问题分开：
+
+| 来源报告 / F-ID或稳定章节 | 上轮问题与结论 | 已有处置 / 修后版本 | 本轮结果 | 当前证据 / 验证 | 剩余动作 |
+| --- | --- | --- | --- | --- | --- |
+
+- 本轮结果统一用：**已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**。已解决需符合原问题的关闭判据；回归需有先前解决及当前再次失败的证据；不再适用须有范围/契约变化依据，不代表实际修复。缺证不能记关闭，未选中的旧项标本轮未复核。
+- 来源身份使用“报告路径/原始版本 + F-ID”，有台账时同时保留评审对象 ID；同一链路沿用旧编号。多份报告的同号问题不合并，新问题分配未占用编号并明确属于本轮；同根因合并时保留来源映射，不重新编号抹掉历史。
+- 默认覆盖上轮全部问题及待核实项；用户限定范围时逐项列出未复核项或其完整 ID 清单。读取处置记录后独立核对实际结果，保留旧证据是否仍适用的理由；只检查修复影响到的必要回归，不自动重跑无关全量验证。
+- 总结分别给出“旧问题解决情况”“修复引入的新问题”“未覆盖/缺证范围”。本轮没有新增 findings 不等于旧问题已关闭；部分通过不扩大成整体通过。复审表结果是检查结论，SDLC 回写仍按仓内协议的固定状态与范围登记，不自造 state 枚举。
+
 ## 什么进入 findings
 
 确认的问题须同时具备：计划中的可定位主张或缺口、已核实的依据、具体触发/受影响场景、对本期目标的实际后果、可执行的最小修订。建议作者换个人偏好的技术、堆更多章节、覆盖无关老问题，都不算。
@@ -48,7 +78,7 @@
 2. **待核实/待决策**：每项写缺什么证据、影响哪个决定/任务、谁可提供以及最晚确认点；责任人未知就写待指定，不虚构用户承诺。
 3. **覆盖摘要**：记录计划与代码基线、实际 agent 分工、四维覆盖/跳过理由、脚本及浏览器实际执行情况。只列结论相关来源，不倾倒阅读日志。无 UI 可写不适用；交付可用性不能随 UI 一起跳过。
 4. **映射与实施编排**：列断链 ID 或确认映射完整的核对范围；给依赖边、并行波次、共享文件/资源负责人角色和汇合验收。现有编排成立时简要确认并引用原计划，只展开有必要调整的部分，不重抄完整映射或为形式新增里程碑/过程文档。只报文件不冲突、不报依赖条件的“可并行”不合格。小计划可合成一张短表。
-5. **总体结论与修订顺序**：建议状态、理由、与原状态的差异，先纠正前提/契约，再修设计、映射与编排；写清解除阻塞的可观察条件。
+5. **总体结论与修订顺序**：首行写「是否需要修改：需要 / 无需」（见下文），再写建议状态、理由、与原状态的差异，先纠正前提/契约，再修设计、映射与编排；写清解除阻塞的可观察条件。
 
 ### 就绪判断（沿用 dev-plan 的含义）
 
@@ -57,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

@@ -1,6 +1,7 @@
 ---
 name: review-prd
-description: 评审既有 PRD 或产品需求文档，核实代码现状与依赖，审查创新性、先进性、可用性、便捷体验、美观 UI、AI 赋能、SMAR、UAT 预期状态及分期终验，默认将完整评审报告落盘。用户要求 review-prd、review PRD、需求评审或检查需求是否合理且可验收时使用；不用于从零写 PRD、评审技术开发计划或仅审查代码 diff。
+argument-hint: "<PRD路径/链接/内容> [上轮报告] [复审/完整评审] [问题ID/范围] [报告路径] [仅聊天]"
+description: 用于评审既有 PRD 的合理性、产品质量与可验收性；不用于从零写 PRD、评审技术计划或代码 diff。核实代码现状、需求、体验、UAT 与分期，默认落盘报告。
 ---
 
 # review-prd · 基于代码事实的产品需求评审
@@ -13,7 +14,7 @@ description: 评审既有 PRD 或产品需求文档，核实代码现状与依
 
 ## 边界与参考
 
-- 默认审查整份 PRD；指定差异或局部范围时，同时追踪受影响的场景、需求、验收和分期。原 PRD 与代码保持只读，默认写入仅限独立评审报告；不自动实现、改稿、写 SPMS 或发送评论。用户明确要求修订时，先形成可追踪的问题，再统一修订并复核；报告保留处置记录，PRD 正文只保留修订后的产品结论。
+- 默认审查整份 PRD；指定差异或局部范围时，同时追踪受影响的场景、需求、验收和分期。原 PRD 与代码保持只读，默认写入为独立评审报告及已启用台账的事实索引（见文末）；不自动实现、改稿、写 SPMS 或发送评论。用户明确要求修订时，先形成可追踪的问题，再统一修订并复核；报告保留处置记录，PRD 正文只保留修订后的产品结论。
 - 区分**现状事实、目标能力、用户/平台约束、未证实假设、验收门槛与观察/PoC 基线**。新能力尚未实现不是 PRD 缺陷；代码当前行为也不是禁止产品演进的理由。报告指出增量与前置，不擅自把当前实现固化为需求。
 - PRD 回答 what / why / 怎样算完成。用户旅程、信息层级、视觉要求、AI 产品行为属于产品设计；内部架构、表结构、端点拆分、模型/算法选型与技术里程碑属于开发计划。UAT 定义角色、场景、预期状态与清晰判据；测试脚本、造数、故障注入、工具及 TC 创建属于测试计划。已给定技术约束、外部产品契约与作为产品能力的评测台可以保留，不能机械按技术词判越界。
 - 在可用时读取 `prd/references/product-quality.md` 校准产品质量规则；采用该模板的文档再按需读 `prd/references/prd-skeleton.md`。找不到 `prd` 时继续按本技能的实质标准评审，不要求安装依赖。用户自定义模板或历史 PRD 不因章节名、编号、缺少 TC 或未录入 SPMS 被判不合格。
@@ -27,6 +28,18 @@ description: 评审既有 PRD 或产品需求文档，核实代码现状与依
 4. 将会改变产品选择的现状主张和前置条件列入核实清单：声称已支持、未支持、可复用、无需改动、兼容、已验证及性能数字等。标清它们是事实还是未来目标。
 5. 读取 [references/report-contract.md](references/report-contract.md)，确定报告路径；记录四个审查维度及代码核实、报告写入、回读核验的状态。事实能查就先查，只向用户询问无法从证据推出的产品决定；缺少某项输入时继续不依赖它的审查。
 
+## 修复效果复审
+
+用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+
+- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
+- 当前原文可由上轮报告的“评审对象”引用定位，按报告目录解析相对路径并核实身份；原文参数可在唯一明确时省略。读取已有处置节或 applied 文档，逐项验证原问题和修订影响的关联内容，不把“已 applied”直接当复审通过。
+- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+
+```text
+$review-prd docs/PRD-login.md，对照 docs/PRD-login.review.md 复审修复效果，逐项记录结果。
+```
+
 ## 2. 编排四个审查视角
 
 先读 [references/review-lenses.md](references/review-lenses.md) 的对应节，再分派。各视角都以用户约束为边界，不为凑问题扩大产品范围。
@@ -76,9 +89,27 @@ PRD 与基线：{PRD 绝对路径及版本；代码仓根、commit/dirty、日
 
 报告至少包含：
 
+- 报告头的「评审对象」：原 PRD 的可点击引用、类型、所审版本与范围；本地路径相对实际报告目录，回读时核验，使 `apply-doc-review` 可仅接收报告参数。
 - 按严重度排序且可定位的问题，附用户场景、实际后果、行为级证据、最小产品修订与复核条件。
 - 代码现状核实矩阵、关键依赖和待核实项；区分静态代码、现有测试、实际运行与浏览器证据，不把尚待开发的目标报成当前缺陷。
 - 四维覆盖及六个产品设计维度的实质结论、SMAR/UAT 与分期终验的断链；不因缺少固定章节或 TC 判错。
 - 建议结论 **通过 / 需修订 / 需补证**，写清阻塞范围与解除条件；有价值的非阻塞机会与修订优先顺序。
 
 **评审通过仅表示在已核实范围内可作为开发/测试计划的输入，不表示功能已实现、性能已实测、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`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+
+每次实际评审登记独立评审 ID、PRD 版本、覆盖范围、原结论与报告路径；复审关联前轮，保留历史，不因通过改写 PRD 实施状态。台账更新属于已有跟进协议的产物索引，不修改原 PRD。

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

@@ -8,6 +8,36 @@
 - 主 agent 单写完整报告并回读实际文件，核对 findings、待核实项、代码矩阵、覆盖、映射/分期、结论和修订顺序齐全；检查引用定位与文件链接。空 findings、缺源码或「需补证」不免除落盘。
 - 最终聊天给实际报告链接、结论与关键摘要；仅聊天模式在聊天交付完整报告。写入工具不可用或失败时明确「报告未落盘」、原因与目标路径，在聊天保留完整结果，将保存标为未完成；不能链接不存在的文件。
 
+## 原文档引用（报告头）
+
+报告标题后、findings 前必须写「评审对象」，供 `apply-doc-review` 仅凭报告定位原文；即使没有 findings 也保留。每个实际评审目标一行，背景资料和关联计划不混作修订目标。
+
+```markdown
+## 评审对象
+
+| 类型 | 原文档 | 所审版本 | 评审范围 |
+| --- | --- | --- | --- |
+| PRD | [<原文档标题>](<相对报告所在目录的原文路径或稳定 URL>) | <内容 hash / 可取回版本；不可得则 unknown> | <全文或指定章节/需求 ID> |
+```
+
+- 本地链接按**实际报告所在目录**计算，不能按当前工作目录、仓根或默认报告位置计算；含空格路径使用合法 Markdown 链接语法。不写机器绝对路径，原文位置与文件名不变。另存到指定目录或带日期的报告时重新核对链接。
+- 远程原文用稳定 URL 并注明可用版本；输入只有聊天文本且没有持久原文时，原文档栏写「聊天输入，无原文路径」，不伪造链接，说明 apply 时需可定位的目标。
+- 回读报告时沿引用打开原文，核对类型、身份、版本与范围；原文已变化时说明所审基线及适用性。后续处置保留此处的历史所审版本，修后版本写入处置节。
+
+## 复审记录
+
+复审报告在标题及评审对象之后注明：上轮报告的相对链接与版本、所审对象的前后版本、本轮范围、已有处置记录链接，以及“修复效果复审”或“完整重审”。历史报告与原结论保持不变；默认按本合同另存新报告。
+
+在原报告结构中增加“上轮问题复审”表，与本轮新增问题分开：
+
+| 来源报告 / F-ID或稳定章节 | 上轮问题与结论 | 已有处置 / 修后版本 | 本轮结果 | 当前证据 / 验证 | 剩余动作 |
+| --- | --- | --- | --- | --- | --- |
+
+- 本轮结果统一用：**已解决、仍存在、部分解决、回归、待核实、不再适用、本轮未复核**。已解决需符合原问题的关闭判据；回归需有先前解决及当前再次失败的证据；不再适用须有范围/契约变化依据，不代表实际修复。缺证不能记关闭，未选中的旧项标本轮未复核。
+- 来源身份使用“报告路径/原始版本 + F-ID”，有台账时同时保留评审对象 ID；同一链路沿用旧编号。多份报告的同号问题不合并，新问题分配未占用编号并明确属于本轮；同根因合并时保留来源映射，不重新编号抹掉历史。
+- 默认覆盖上轮全部问题及待核实项；用户限定范围时逐项列出未复核项或其完整 ID 清单。读取处置记录后独立核对实际结果，保留旧证据是否仍适用的理由；只检查修复影响到的必要回归，不自动重跑无关全量验证。
+- 总结分别给出“旧问题解决情况”“修复引入的新问题”“未覆盖/缺证范围”。本轮没有新增 findings 不等于旧问题已关闭；部分通过不扩大成整体通过。复审表结果是检查结论，SDLC 回写仍按仓内协议的固定状态与范围登记，不自造 state 枚举。
+
 ## 什么进入 findings
 
 确认的问题同时具备：PRD 可定位的主张/缺口、已核实依据、具体用户场景/触发、对已确认目标的实际后果、可执行的最小产品修订。每条一个独立根因，重复症状合并但保留关键定位。纯格式、偏好或无关旧代码问题不进入 findings。
@@ -49,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 核实，超出则反馈拆期。