@xgent-ai/skills 0.7.5 → 0.7.6

package/skills/review-code/SKILL.md

@@ -2,32 +2,140 @@
 name: review-code
 argument-hint: "[开发计划] [未提交/commit/A..B/基准分支] [上轮报告] [复审/完整评审] [问题ID/文件范围] [报告路径] [仅聊天]"
 description: 用于评审代码 diff、提交、分支差异或开发计划登记的提交及修复复审；不用于单独评审计划、全仓普查或直接修复。核对旧问题与新增回归，落盘报告并判定是否需修改。
+disable-model-invocation: true
 ---
 
 # review-code · 代码变更评审
 
-判断本次变更是否引入值得作者修复的缺陷，以及是否满足本次承诺的行为。以 Codex 原生 review 的缺陷门槛为准，补充需求符合性、跨文件影响和验证证据；不以问题数量衡量评审质量。
+按以下 ODC 声明完成代码变更评审；列表逐项适用。引用路径相对本文件解析，按阶段读取：
 
-**默认交付是完整 Markdown 报告：实际写入文件、回读核验，聊天给结论摘要与文件链接。用户明确要求仅聊天或不写文件时例外。** 代码和计划默认只读，不自动修复、更新计划进度、提交、发 PR 评论或审批 PR。用户同时授权修复时，先保留原始评审基线，再执行修复并区分复核结果。
+- 确定模式与版本时读 [输入范围与 Git 取证](references/git-scopes.md)。
+- 理解行为与选择审查深度时读 [审查视角与取舍](references/review-lenses.md)。
+- 确定报告路径、复审约定、问题格式与验收判定时读 [问题与报告合同](references/report-contract.md)。
 
-`references/` 相对本文件解析；目标仓路径、技术栈、规则和工具在运行时发现。语言跟随用户。本 skill 可独立工作，不依赖本机安装 Codex CLI 或社区 skill。
+```formal
+INTENT:
+  GOAL: assess_actionable_defects_and_promised_behavior_of_code_changes
+  SCOPE: [requested_diff, relevant_cross_file_impact, requirement_compliance,
+          verification_evidence, repair_effect_recheck]
+  SUCCESS: [evidence_grounded_conclusions, explicit_coverage_and_limits,
+            complete_report_delivered]
+  NON_GOALS: [plan_only_review, whole_repository_audit, unrequested_repairs]
+
+RULE @review_standard:
+  MUST: codex_native_review_defect_threshold
+  MUST_NOT: finding_count_as_quality_metric
+
+RULE @review_boundary:
+  MUST: code_and_plan_read_only_by_default
+  MUST_NOT: [automatic_repairs, automatic_plan_progress_updates, automatic_commits,
+             automatic_pr_comments, automatic_pr_approval]
+
+RULE @authorized_repairs:
+  WHEN: user_also_authorized_repairs
+  MUST: [preserve_original_review_baseline_before_repairs,
+         distinguish_post_repair_recheck_results]
+
+RULE @runtime_context:
+  MUST: [discover_target_repository_paths_stack_rules_and_tools_at_runtime,
+         follow_user_language, work_independently_of_locally_installed_codex_cli_or_community_skills]
+
+WORKFLOW @review_code:
+  DO: [read_applicable_instructions_and_summarize_intent,
+       resolve_and_freeze_review_scope_and_report_path,
+       establish_coverage_checklist,
+       recheck_previous_issues_when_applicable,
+       read_diff_and_trace_required_behavior,
+       validate_and_countercheck_candidate_findings,
+       adjudicate_and_recheck_snapshot_consistency,
+       write_and_reread_complete_report_unless_chat_only,
+       write_registered_project_status_after_primary_artifact_delivery_when_allowed,
+       deliver_verdict_report_link_and_next_step_commands]
+  OUTPUT: code_change_review_report
+```
 
 ## 1. 确定审查对象
 
-1. 读取适用的仓库和子目录指令、review 专项约定。用一句话概括变更意图，区分用户明确要求与从代码推断的意图；缺少提交说明不自动中止评审。
-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) 确定报告路径。建立简短覆盖清单：变更文件/行为、必要上下游、计划范围（若有）、验证方式、证据缺口、落盘和回读。
+```formal
+RULE @scope_evidence:
+  MUST: [read_repository_subdirectory_and_review_specific_instructions,
+         summarize_change_intent_in_one_sentence,
+         distinguish_explicit_user_requirements_from_code_inferred_intent,
+         resolve_input_using_git_scopes_reference,
+         freeze_repository_root_mode_base_and_target_sha,
+         freeze_worktree_snapshot_file_limits_and_optional_plan_version]
+  MUST_NOT: missing_commit_message_automatically_stops_review
+
+RULE @plan_default:
+  WHEN: only_development_plan_given_without_another_explicit_mode
+  MUST: use_plan_registered_commits_and_current_uncommitted_changes_as_scope
+
+RULE @uncommitted_default:
+  WHEN: no_mode_specified_and_uncommitted_changes_exist_and_plan_default_does_not_apply
+  MUST: declare_uncommitted_mode
+
+RULE @initial_review_without_target:
+  WHEN: initial_review_with_clean_worktree_and_no_explicit_target
+  MUST: ask_for_review_target
+  MUST_NOT: [silently_choose_latest_commit, silently_choose_default_main_branch]
+
+RULE @ambiguous_scope:
+  WHEN: conflicting_modes_or_missing_ref_or_ambiguous_range_endpoints
+  MUST: [clarify_affected_scope, allow_independent_instruction_reading]
+  MUST_NOT: [silently_replace_baseline, silently_expand_to_whole_repository]
+
+RULE @coverage_checklist:
+  MUST: [resolve_report_path_using_report_contract,
+         list_changed_files_and_behaviors_required_upstream_and_downstream,
+         list_plan_scope_if_any_verification_methods_and_evidence_gaps,
+         include_report_write_and_reread]
+```
 
 ## 修复效果复审
 
-用户要求“复审 / re-review / 检查修复效果”时启用；开发计划模式下已有本计划的代码评审报告时也默认启用，以轮次最大的报告为上轮。要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文、报告轮次或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+```formal
+RULE @recheck_selection:
+  WHEN: explicit_recheck_or_plan_mode_with_existing_code_review_report
+  MUST: [enable_repair_effect_recheck, read_report_contract_recheck_terms,
+         default_to_highest_report_round_as_previous_in_plan_mode,
+         honor_explicit_full_review_request_with_full_review_process,
+         locate_previous_report_from_user_input_context_round_or_explicit_record_link]
+  MUST_NOT: choose_ambiguous_previous_report_by_latest_file_mtime
+  ON_UNMET: clarify_only_ambiguous_scope
+
+RULE @recheck_coverage:
+  WHEN: repair_effect_recheck
+  MUST: [default_cover_all_previous_issues_unverified_items_and_direct_repair_regressions,
+         honor_user_selected_ids_or_scope_and_mark_others_unreviewed,
+         recheck_each_old_issue_in_current_code,
+         inspect_repair_diff_for_newly_introduced_or_activated_defects]
+  MUST_NOT: [require_old_issue_to_overlap_repair_diff,
+             require_old_issue_to_be_introduced_by_current_repair,
+             present_remaining_old_issue_as_new_finding]
+
+RULE @missing_previous_report:
+  WHEN: recheck_requested_without_usable_previous_report
+  MUST: allow_current_target_review
+  MUST_NOT: claim_previous_issues_individually_closed
 
-- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
-- 复审分两部分：按上轮报告逐项核对当前代码中的旧问题；按本次修复 diff 检查新引入或激活的问题。旧问题的复核不要求落在本次 diff，也不要求由本次修复引入；仍存在的旧问题列复审表并影响修复有效性结论，不冒充本轮新增 finding。
-- 明确上轮审查基线、修复差异范围与当前核查版本，三者可不同。用户未给新 diff 时，可从报告可解析的版本到当前目标确定并声明范围；无法确定时只核对有证据的旧问题，新增问题检查标受限。工作树干净不妨碍旧问题复核；不得沿用初审的无 diff 规则直接判无可审内容。
-- 新 findings 继续遵守下文的 diff 归因与定位门槛；旧问题复核按报告合同单列，不被这些门槛过滤。只看修复增量不能声称已重新完整审查原变更。
-- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+RULE @recheck_versions:
+  WHEN: repair_effect_recheck
+  MUST: [distinguish_previous_review_baseline_repair_diff_and_current_checked_version,
+         derive_and_declare_diff_from_parseable_report_version_when_user_omits_new_diff,
+         recheck_evidenced_old_issues_and_limit_new_issue_check_when_diff_is_unknown,
+         recheck_old_issues_even_with_clean_worktree]
+  MUST_NOT: [apply_initial_no_diff_rule_to_skip_old_issue_recheck,
+             claim_full_original_change_review_from_repair_increment_only]
+
+RULE @recheck_delivery:
+  WHEN: repair_effect_recheck
+  MUST: [apply_new_finding_gates_only_to_new_findings,
+         output_issue_by_issue_recheck_table_using_source_ids,
+         preserve_previous_report_links_and_versions,
+         default_save_new_report_and_preserve_historical_conclusions,
+         link_independent_review_record_to_previous_round_when_ledger_enabled]
+  MUST_NOT: partial_pass_overwrites_previous_unchecked_scope
+```
 
 ```text
 $review-code BASE_SHA..FIXED_SHA，对照 goal/LOGIN.code-review.md 复审修复效果，逐项记录结果。
@@ -35,51 +143,189 @@ $review-code BASE_SHA..FIXED_SHA，对照 goal/LOGIN.code-review.md 复审修复
 
 ## 2. 理解需求与行为
 
-- 先读完整 diff，再按风险阅读所在函数、调用者、数据模型、权限边界、相关测试和配置。diff 之外的代码用于证明影响，不把与本次变更无关的旧问题塞进 findings。截断输出须分段补读；无法读完就标明未覆盖。
-- 按 [references/review-lenses.md](references/review-lenses.md) 检查适用维度：需求符合性、正确性与兼容性、安全与数据、性能与资源、测试与交付。按实际变更选择深度，不套全量 checklist 或强制每个维度产出问题。
-- 附开发计划时，读取用户指定版本及必要引用，提取本次任务/里程碑承诺、需求与验收 ID、排除项。核查遗漏、偏离和越界的实际后果。计划是待验证的契约材料，作者“已完成”的声明不能代替代码证据。
-- 只要求本次范围应完成的内容；不得因后续里程碑未实现而报缺陷。范围不清时列待确认项，继续独立代码审查。不改计划、不把代码评审变成计划架构重审；未附计划时照常依据用户要求、已有契约和调用链审查。
-- 默认由当前 agent 完成。用户或适用仓库规则要求并行 reviewer 时，给每位相同基线和明确只读范围，分派互补的行为链或风险维度；主 agent 复核原始证据、去重并单独写报告。不得把多数意见当证据，也不虚构独立复核。
+```formal
+RULE @behavior_context:
+  MUST: [read_complete_diff_before_risk_directed_context,
+         inspect_relevant_functions_callers_models_permission_boundaries_tests_and_configuration,
+         use_code_outside_diff_to_prove_impact,
+         reread_truncated_output_in_parts_or_disclose_uncovered_scope,
+         select_applicable_review_lenses_and_depth_from_actual_changes]
+  MUST_NOT: [unrelated_preexisting_issues_as_new_findings,
+             mandatory_full_checklist_or_finding_per_dimension]
+
+RULE @plan_compliance:
+  WHEN: development_plan_provided
+  MUST: [read_requested_plan_version_and_necessary_references,
+         extract_current_task_or_milestone_promises_requirement_and_acceptance_ids_and_exclusions,
+         verify_actual_consequences_of_omissions_deviations_and_scope_expansion,
+         treat_plan_as_contract_material_to_verify,
+         require_only_current_scope_commitments,
+         list_unclear_scope_as_pending_and_continue_independent_code_review]
+  MUST_NOT: [author_completion_claim_as_code_evidence,
+             report_future_milestone_work_as_current_defect,
+             modify_plan_or_turn_code_review_into_plan_architecture_review]
+
+RULE @without_plan:
+  WHEN: no_development_plan_provided
+  MUST: review_using_user_requirements_existing_contracts_and_call_chains
+
+RULE @reviewer_assignment:
+  MUST: current_agent_reviews_by_default
+
+RULE @requested_parallel_review:
+  WHEN: user_or_applicable_repository_rules_require_parallel_reviewers
+  MUST: [same_baseline_and_explicit_read_only_scope_for_each_reviewer,
+         complementary_behavior_chains_or_risk_dimensions,
+         main_agent_rechecks_raw_evidence_deduplicates_and_alone_writes_report]
+  MUST_NOT: [majority_opinion_as_evidence, fabricated_independent_review]
+```
 
 ## 3. 验证候选问题
 
-每个进入本轮新增 findings 的问题必须同时满足（旧问题按复审表独立核对）：
+```formal
+RULE @new_finding_admission:
+  WHEN: candidate_enters_current_round_new_findings
+  MUST: [introduced_or_actually_activated_by_reviewed_change,
+         explain_baseline_to_target_behavior_difference,
+         prove_causal_chain_when_change_makes_old_code_newly_reachable,
+         concrete_reachable_input_or_state_and_failure_behavior,
+         identify_affected_caller_or_contract_and_minimal_repair_direction,
+         material_correctness_security_performance_or_maintainability_impact,
+         repair_expectation_matches_actual_repository_standards,
+         directly_read_target_code_and_relevant_requirements_or_rules,
+         verify_explicit_behavior_changes_against_promised_contracts,
+         use_minimal_reproduction_when_needed]
+  MUST_NOT: [vague_possible_cross_module_impact,
+             pure_style_personal_preference_unrelated_refactor_or_speculative_defense,
+             rely_on_unexpressed_author_intent,
+             intentional_behavior_change_alone_as_bug]
+  # 旧问题按复审表独立核对。
 
-1. **由本次变更引入或实际激活**：能说明基线与目标行为的差别；若改动让旧代码新近可达，证明这条因果链。
-2. **具体且可执行**：有真实可达的输入/状态、故障行为、受影响调用方或契约，以及最小修复方向。不能只说“可能影响其他模块”。
-3. **有实质影响**：影响正确性、安全、性能或可维护性，且修复要求符合该仓库实际标准。纯风格、个人偏好、无关重构和假设性的防御代码不报。
-4. **证据足够**：直接阅读目标版本代码、相关需求/规则，必要时做最小复现；不能依赖作者未表达的意图。明确的行为变更本身不是 bug，但仍要验证它是否破坏承诺的契约。
+RULE @existing_protection:
+  MUST: check_existing_validation_types_upstream_filters_transactions_and_compensation
+  MUST_NOT: infer_failure_only_from_missing_local_try_catch_null_check_or_cache
 
-验证时：
+RULE @verification_execution:
+  WHEN: validating_review_candidate
+  MUST: [choose_existing_tests_type_checks_or_minimal_experiments_relevant_to_behavior,
+         read_commands_and_configuration_before_execution,
+         use_isolated_temporary_directory_for_written_reproductions,
+         record_command_tested_version_actual_result_and_limits,
+         mark_passed_only_after_actual_execution]
+  MUST_NOT: [automatic_fixes_snapshot_updates_migrations_or_deployments,
+             access_real_business_data,
+             add_tests_or_repairs_to_target_repository,
+             mandatory_unrelated_full_test_suite,
+             test_pass_replaces_requirement_check]
+  ON_UNMET: retain_sufficient_static_evidence_or_list_unverified_item
 
-- 先检查现有校验、类型约束、上游过滤、事务或补偿是否已处理该场景；不因局部缺少 `try/catch`、空值判断或缓存就推断故障。
-- 选择能验证该行为的现有测试、类型检查或最小实验，先读命令及相关配置，避免自动修复、快照更新、迁移、部署或访问真实业务数据。需要写临时复现时使用隔离临时目录；不向目标代码库添加测试或修复。
-- 实际执行才记为“通过”；写明命令、所测版本、结果和限制。无法运行时保留充分的静态证据或列待核实项，不强制运行无关全量测试，也不用测试通过替代需求检查。
-- 历史 commit/范围的运行验证必须使用对应目标快照；当前 checkout 的测试不能证明另一 commit。对原有失败与新增失败做必要的基线比较。
-- 技术结论依赖外部接口或版本且本地无法确证时，查对应版本的官方资料并引用；不可访问时说明证据缺口。性能问题说明实际数据规模/复杂度，安全问题说明输入可控性与可达路径，不把模式匹配当漏洞结论。
-- 对每条候选做反证复核。按根因和修复动作合并重复，保留所有独立有效问题；不设数量指标，不只留最严重几条。证据不足移入待核实项，不能降为 P3 混入 findings。
+RULE @historical_verification:
+  WHEN: reviewing_historical_commit_or_range
+  MUST: [run_verification_on_corresponding_target_snapshot,
+         compare_baseline_when_needed_to_distinguish_existing_and_new_failures]
+  MUST_NOT: current_checkout_test_proves_another_commit
+
+RULE @external_and_domain_evidence:
+  MUST: [consult_and_cite_version_matched_official_material_when_local_evidence_cannot_confirm_external_contract,
+         disclose_evidence_gap_when_material_unavailable,
+         state_actual_data_scale_or_complexity_for_performance_issue,
+         state_input_control_and_reachable_path_for_security_issue]
+  MUST_NOT: pattern_match_alone_as_vulnerability_conclusion
+
+RULE @candidate_countercheck:
+  MUST: [seek_counterevidence_for_each_candidate,
+         merge_duplicates_by_root_cause_and_repair_action,
+         retain_all_independent_valid_issues,
+         move_insufficiently_evidenced_candidates_to_unverified_items]
+  MUST_NOT: [finding_quota, keep_only_most_severe_few, uncertain_issue_disguised_as_p3]
+```
 
 ## 4. 裁定、落盘与交付
 
-1. 按报告合同写精确短定位、单段问题说明、P0–P3 和置信度。新增 findings 的主定位须与所审 diff 重叠；旧问题复审及支持证据可在 diff 之外。规则对结论有实质贡献时，附该规则的文件和最小行范围。
-2. 核对覆盖清单以及版本是否发生变化。相关文件或计划变动时重审受影响结论；不能收敛时保留快照版本与缺口。报告新文件不纳入本轮审查对象。
-3. 完整报告先写评审对象，再列确认问题、待核实项、覆盖与验证、可选计划符合性、总体结论和修复顺序。默认采用 `patch is correct / patch is incorrect / inconclusive`；最后一项是本 skill 为证据不足增加的状态，不伪称原生 Codex JSON 值。总体结论首行写验收判定。
-4. 写入并回读报告，检查问题、证据、基线、限制和结论完整，链接指向实际文件。空 findings 或无法充分验证也要保存；写入失败如实说明未落盘，聊天交付完整内容，不能宣称完成保存。
+```formal
+RULE @finding_presentation:
+  MUST: [follow_report_contract_short_precise_location_single_paragraph_p0_to_p3_and_confidence,
+         new_finding_primary_location_overlaps_reviewed_diff,
+         allow_old_issue_recheck_and_supporting_evidence_outside_diff,
+         cite_applicable_rule_file_and_minimal_line_range_when_material_to_conclusion]
+
+RULE @snapshot_consistency:
+  MUST: [recheck_coverage_checklist_and_version_changes,
+         recheck_affected_conclusions_when_relevant_files_or_plan_change,
+         retain_snapshot_version_and_gaps_when_changes_cannot_converge]
+  MUST_NOT: new_report_file_becomes_current_review_input
+
+RULE @complete_report:
+  MUST: [review_object_before_findings,
+         confirmed_findings_unverified_items_coverage_and_verification,
+         plan_compliance_only_when_plan_provided,
+         overall_conclusion_and_repair_order,
+         acceptance_verdict_on_first_line_of_overall_conclusion]
+  # 正确性结论默认使用原词；inconclusive 是本 skill 的证据不足扩展。
+  MUST_NOT: claim_inconclusive_is_native_codex_json_value
+
+RULE @report_persistence:
+  UNLESS: user_explicitly_requests_chat_only_or_no_file
+  MUST: [write_complete_markdown_report_even_with_empty_findings_or_insufficient_verification,
+         reread_actual_report_for_findings_evidence_baseline_limits_and_conclusion,
+         link_actual_existing_file]
+  ON_UNMET: [state_report_not_saved_and_reason_and_target_path,
+             deliver_complete_report_in_chat,
+             do_not_claim_successful_save]
+
+OUTPUT:
+  FORMAT: markdown
+  STYLE: follow_user_language
+  SECTIONS: [acceptance_verdict, report_link, overall_conclusion,
+             important_findings_or_limits, copyable_next_step_commands]
+  correctness_values: ["patch is correct", "patch is incorrect", inconclusive]
+  verdict_source: references/report-contract.md
+
+REVIEW:
+  CHECK: [@new_finding_admission, @recheck_coverage, @snapshot_consistency,
+          @complete_report, @report_persistence]
+  ALSO: [coverage_disclosure, evidence_traceability, actual_report_links]
+  EXPOSE: on_issue
+```
 
 ## 5. 验收判定与下一步
 
-计划实施完成后，代码评审是验收守门：「评审 → 修复 → 复审」循环，直到通过验收或用户明确本期放过。最终回复先给一行验收判定（定义见[报告合同](references/report-contract.md)的「验收判定」），再给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex `$apply-code-review`、Claude Code `/apply-code-review`），路径填实际文件。
+```formal
+RULE @acceptance_continuation:
+  MUST: [code_review_as_acceptance_gate_after_plan_implementation,
+         review_repair_recheck_continuation_until_pass_or_explicit_user_waiver,
+         final_reply_starts_with_contract_acceptance_verdict,
+         next_step_commands_use_current_client_skill_syntax_and_actual_paths]
+  MUST_NOT: automatically_start_repairs_rechecks_ui_acceptance_or_prd_gap_review
+
+RULE @needs_changes_next:
+  WHEN: "验收判定为「需要修改」"
+  MUST: suggest_apply_code_review_with_current_report_then_review_code_recheck
 
-| 验收判定 | 下一步 |
-| --- | --- |
-| 需要修改 | `apply-code-review <本报告路径>`；修复后再用本技能复审 |
-| 通过验收 / 用户豁免通过 | 变更涉及界面、且还没有覆盖当前版本的 UI 验收通过时，可选 `review-ui <计划路径>` 做 UI/UX 验收；计划来自 PRD 时，可选 `review-prd-dev-gaps <计划路径>` 核对该期 PRD 覆盖；都不适用时说明本计划代码验收完成 |
-| 需补证 | 列出所缺证据或验证及获取方式，补齐后再次 `review-code <计划路径或原范围>` |
+RULE @passed_next:
+  WHEN: "验收判定为「通过验收」或「用户豁免通过」"
+  MUST: |
+    变更涉及界面且没有覆盖当前版本的 UI 验收通过时，可选 review-ui <计划路径>；
+    计划来自 PRD 时，可选 review-prd-dev-gaps <计划路径>；
+    都不适用时说明本计划代码验收完成。仍有 P3 时，可选
+    apply-code-review <本报告路径>，处理后照常复审。
 
-- 计划是否来自 PRD 以计划顶部「需求来源」为准；旧计划没有该行时，账本来源明确指向 PRD 的也算。未附计划时不提示差异核查。
-- 通过验收但仍有 P3 时，可选用 `apply-code-review <本报告路径>` 处理，处理后照常复审。
-- 用户在评审后或调用时明确表示本期放过剩余问题，按报告合同在本轮报告追加豁免记录并回读，再按通过给下一步；不把豁免写成已修复。
-- 只给出建议命令，不自行启动修复、复审、UI 验收或差异核查。
+RULE @prd_origin:
+  MUST: |
+    计划是否来自 PRD，以计划顶部「需求来源」为准；旧计划没有该行时，
+    账本来源明确指向 PRD 的也算。未附计划时不提示差异核查。
+
+RULE @needs_evidence_next:
+  WHEN: "验收判定为「需补证」"
+  MUST: [list_missing_evidence_or_verification_and_how_to_obtain,
+         suggest_review_code_with_plan_or_original_scope_after_evidence_ready]
+
+RULE @explicit_waiver:
+  WHEN: user_explicitly_waives_remaining_issues_for_current_period_at_invocation_or_after_review
+  MUST: [append_contract_waiver_record_to_current_report_and_reread,
+         give_passed_next_steps]
+  MUST_NOT: waiver_described_as_repaired
+```
 
 调用示例（自然语言参数，不要求专用解析器）：
 
@@ -95,6 +341,22 @@ $review-code BASE_SHA..FIXED_SHA，对照 goal/LOGIN.code-review.md 复审修复
 
 ## 项目状态回写
 
-若仓库已登记状态台账，或存在仓根 `.xgent-ai/sdlc/protocol.md`（兼容已有 `docs/project-status/protocol.md`；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。
+```formal
+RULE @project_status:
+  WHEN: repository_has_registered_ledger_or_existing_sdlc_protocol
+  MUST: |
+    交付原产物后读取仓内回写规则；默认协议为仓根 .xgent-ai/sdlc/protocol.md，
+    兼容已有 docs/project-status/protocol.md。两套并存且未登记切换时先核对，不双写。
+    按协议更新受影响对象当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，
+    事件留存条件或旧版事件要求以仓内协议为准。只读／仅聊天／不保存要求优先；
+    登记失败须说明，不影响如实交付已完成的原产物。
+  MUST_NOT: [create_ledger_when_not_enabled, require_separately_installed_skill]
 
-每次实际评审登记独立评审 ID、精确 base/target 或工作树指纹、范围、结论和报告路径；计划关联以实际输入为准，允许没有计划的评审。复审关联前轮，不覆盖旧结论；不把 patch is correct 登记为已验收、已合并或已发布。
+RULE @review_status_record:
+  WHEN: project_status_writeback_allowed
+  MUST: [independent_id_for_each_actual_review,
+         exact_base_and_target_or_worktree_fingerprint_scope_conclusion_and_report_path,
+         plan_association_only_from_actual_input_and_allow_no_plan,
+         link_recheck_to_previous_round_and_preserve_old_conclusion]
+  MUST_NOT: "将 patch is correct 登记为已验收、已合并或已发布"
+```

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

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

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

@@ -2,20 +2,39 @@
 name: review-dev-plan
 argument-hint: "<计划路径/链接/内容> [上轮报告] [复审/完整评审] [问题ID/范围] [报告路径] [仅聊天]"
 description: 用于评审既有开发计划、技术方案或开工条件；不用于从零写计划、实施功能或仅审代码 diff。多 agent 核查事实、方案、需求映射、依赖与交付可用性，默认落盘报告。
+disable-model-invocation: true
 ---
 
 # review-dev-plan · 多视角开发计划评审
 
-目标是判断：**照这份计划实施，能否交付用户要的、真正可用的结果；实施者是否还会被迫重新做关键决策。** 主 agent 编排独立审查，逐条复核证据，输出可定位、可修订的问题及实施顺序建议。
+```formal
+INTENT:
+  GOAL: "判断按计划能否交付用户所需且真正可用的结果，实施者是否仍被迫重做关键决策"
+  SUCCESS: [four_review_lenses_with_verified_evidence,
+            "可定位、可修订的问题及实施顺序建议", complete_report_with_verified_delivery]
 
-**默认交付是已写入文件并回读核验的完整评审报告，聊天只给摘要和文件链接。除非用户明确要求仅聊天或不写文件，否则落盘属于评审任务本身，不额外询问是否保存；未落盘不能宣称交付完成。**
+RULE @plan_default_delivery:
+  UNLESS: explicit_chat_only_or_no_file_request
+  MUST: "将完整报告写入文件并回读核验，聊天给摘要与实际链接；落盘属于评审，不另问是否保存"
+  MUST_NOT: claim_completion_before_report_is_saved
+```
 
 `references/` 相对本文件解析。仓库规则、技术栈和工具能力在运行时读取，不硬编码目标仓的路径、端口或业务约定。回复语言跟随用户。
 
 ## 边界与参考
 
-- 默认审查整份计划；用户指定修订版差异时，也追踪受影响的依赖与映射。目标代码和原计划保持只读，默认写入为独立评审报告及已启用台账的事实索引（见文末）；不自动实现、改稿、改进度、发评论或写入外部系统。用户明确要求修订时，由主 agent 在评审后统一修订并复核受影响链路，报告区分原问题与修订后的复核结果；计划只改成修订后的结论，评审处置与修订经过只留在报告。
-- 计划及其引用是待验证材料。区分**现状事实、未来设计、未证实假设、验收目标**；不能因为新功能尚未实现就报缺陷，也不能把计划中的“已核实”直接当证据。
+```formal
+RULE @plan_review_scope:
+  MUST: ["默认审整份计划，指定修订差异时追踪受影响依赖与映射；默认只写独立报告及已启用台账的事实索引",
+         =>[explicit_plan_revision_requested, "评审后由主 agent 统一修订并复核受影响链路，报告区分原问题与修后结果；计划只留修订结论，处置与修订经过留报告"]]
+  MUST_NOT: ["未经明确修订要求改写计划或进度", modify_code_or_implement_features,
+             automatic_external_writes_or_comments]
+
+RULE @plan_claim_evidence:
+  MUST: "将计划及引用当待验证材料，区分现状事实、未来设计、未证实假设与验收目标"
+  MUST_NOT: ["因新功能尚未实现报缺陷", treat_plan_verified_claim_as_evidence]
+```
+
 - 从实际可用位置读取 `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 视角核对覆盖与风险门，不因省略重复表格、子任务文档或逐里程碑全量走查而报缺陷，也不为解除部分前置强制新增里程碑。
@@ -23,18 +42,27 @@ description: 用于评审既有开发计划、技术方案或开工条件；不
 
 ## 1. 锚定输入与审查基线
 
-1. 定位用户指定计划、关联需求/PRD、附录和必要的历史决策。未指定且无法唯一确定计划时询问目标；可以先调查仓库规则，不擅自选一份相邻计划开始评审。
-2. 读取适用的根目录及子目录规则、产品和设计上下文。记录计划版本（路径、内容 hash 或可用版本号）、调查日期、代码 commit、dirty 状态；当前工作树是调查事实源时明确写出。
-3. 从计划提取范围与排除、R/NFR/C/A 或等价需求 ID、关键决策、外部契约、交付物、里程碑及前置关系。缺失 ID 可用章节定位，不替作者补造需求。
-4. 读取 [references/report-contract.md](references/report-contract.md)，按其中的「落盘与交付合同」确定输出路径。建一个短任务台账：审查维度、负责人、状态、证据缺口，以及报告写入与回读核验。明确 UI 是否在范围内、是否已有可运行页面/原型、哪些结论必须访问外部服务或官方文档。
+开始时读取 [报告合同](references/report-contract.md)，按其落盘、引用及模式约定执行。
 
-## 修复效果复审
+```formal
+WORKFLOW @plan_review_baseline:
+  DO: ["定位用户指定计划、需求/PRD、附录及必要历史决策；目标不唯一只问目标，可先查规则，不自选相邻计划",
+       "读适用根/子目录规则及产品/设计上下文，记计划路径/hash/可用版本、日期、代码 commit/dirty，明确当前工作树参与调查",
+       "提取范围/排除、R/NFR/C/A 或等价 ID、决策、外部契约、交付物、里程碑与前置；缺 ID 用章节，不替作者造需求",
+       "按报告合同定路径，短台账记维度/负责人/状态/缺口及报告写入/回读；明确 UI 范围、可运行页面/原型，以及需外部服务或官方文档核实的结论"]
+```
 
-用户要求“复审 / re-review / 检查修复效果”时启用；要求完整重审则仍执行完整流程。先读取 [报告合同](references/report-contract.md) 的复审约定。上轮报告以用户指定、当前上下文或明确的记录链接定位；多个候选无法确定时仅澄清对应范围，不按最新文件时间猜选。
+## 修复效果复审
 
-- 默认复审上轮全部问题、待核实项及直接受修复影响的回归；用户指定 ID/范围时只核对该范围，其余明确未复核。没有可用上轮报告时可继续当前对象审查，但不能声称旧问题已逐项关闭。
-- 当前原文可由上轮报告的“评审对象”引用定位，按报告目录解析相对路径并核实身份；原文参数可在唯一明确时省略。读取已有处置节或 applied 文档，逐项验证原问题和修订影响的关联内容，不把“已 applied”直接当复审通过。
-- 输出逐项复审表，沿用来源 ID 并保留上轮报告链接/版本。新一轮默认另存报告，保留历史结论；启用台账时登记独立评审对象并关联前轮，不能用本轮局部通过覆盖前轮未核查范围。
+```formal
+RULE @plan_re_review:
+  WHEN: "用户要求复审 / re-review / 检查修复效果"
+  MUST: ["按报告合同复审；明确要求完整重审时执行完整流程",
+         "按用户指定、当前上下文或明确记录链接找上轮报告，候选不唯一只澄清相关范围，不按文件时间猜选",
+         "默认覆盖上轮全部问题、待核实项和修复直接影响的回归；指定 ID/范围时其余标未复核；缺上轮报告可审当前对象，不声称旧项逐条关闭",
+         "原文可由上轮评审对象引用定位，按报告目录解相对路径并核实身份，唯一明确时可省原文参数；读处置节/applied 文档，独立核对问题与修订关联内容，不以已 applied 判通过",
+         "逐项复审表沿用来源 ID 与上轮链接/版本，默认另存新报告保留历史；启用台账时登记独立评审并关联前轮，局部通过不覆盖未核查范围"]
+```
 
 ```text
 $review-dev-plan goal/LOGIN.md，对照 goal/LOGIN.review.md 复审修复效果，逐项记录结果。
@@ -53,11 +81,20 @@ $review-dev-plan goal/LOGIN.md，对照 goal/LOGIN.review.md 复审修复效果
 
 ### 调度规则
 
-- 默认一视角一 reviewer；简单局部计划可用两位独立 reviewer 各覆盖两个视角，在同一回报内分开标明覆盖与结论，减少调度回合。不得合并后漏审某个维度。模型继承主 agent，不主动覆盖模型或推理档位。所有 reviewer 只读，报告由主 agent 单写，不让多个 agent 改同一文件。
-- 并发数受实际剩余槽位约束，主 agent 也占槽位。只有 4 个总槽位时，先并行 3 个视角，完成后复用空闲 agent 审第 4 个；更少槽位则分批，不能漏掉任何视角。主 agent 同期整理需求账本和全局矛盾。
-- 初轮独立调查，不把主 agent 的预设缺陷或其他 reviewer 的结论当任务答案。每人拿相同基线、用户约束和原始材料；独立返回后再交换相互影响的证据。
-- 共用浏览器会话、可变数据库或外部环境时由主 agent 指定一个操作者，其他 reviewer 读证据；只读代码可并行。评审不执行迁移、种子、部署或有副作用的验收命令。
-- 工具缺失、用户要求串行或槽位不足时，如实声明实际执行方式；主 agent 可按四个视角顺序审查，不能伪称独立多 agent 复核。单个 reviewer 失败时重派一次或主 agent 接管；无法核实的部分留在覆盖缺口中。
+```formal
+RULE @plan_review_scheduling:
+  MUST: ["主 agent 在多 agent 工具可用且当前授权允许时实际启动只读 subagents，默认一视角一 reviewer；简单局部计划可用两位独立 reviewer 各覆盖两个视角，分别标覆盖与结论，不漏维度",
+         "模型继承主 agent，报告由主 agent 单写；按实际剩余槽位安排，主 agent 也占槽，总槽位为 4 时先并行 3 个视角，再复用空闲 agent 审第 4 个，更少则分批",
+         "主 agent 同期整理需求账本和全局矛盾；初轮 reviewer 获相同基线、用户约束和原始材料，独立调查后再交换影响证据，不把预设缺陷或别人结论当答案",
+         "工具缺失、用户要求串行或槽位不足时如实声明方式，主 agent 可顺序审四视角，不伪称独立多 agent 复核"]
+  MUST_NOT: [agent_initiated_model_or_reasoning_override,
+             "reviewer 改原计划/代码、继续派生 agent 或写最终报告"]
+
+RULE @plan_review_resources:
+  MUST: ["主 agent 为共用浏览器、可变数据库或外部环境指定一个操作者，其他 reviewer 读证据；代码可并行只读",
+         =>[reviewer_failed, "重派一次或主 agent 接管，无法核实部分留覆盖缺口"]]
+  MUST_NOT: "执行迁移、种子、部署或有副作用的验收命令"
+```
 
 ### 每个 reviewer 的派发合同
 
@@ -78,28 +115,46 @@ $review-dev-plan goal/LOGIN.md，对照 goal/LOGIN.review.md 复审修复效果
 
 ## 3. 主 agent 交叉复核与裁定
 
-1. 收齐四个视角的结果；逐条阅读支持候选问题的计划段落和原始证据，确认适用范围、代码版本和触发条件。不能把多名 agent 的一致意见当事实。
-2. 对事实冲突、方案依赖、交付断点做针对性追问：例如事实 reviewer 发现某接口不支持分页，则让架构/交付 reviewer 复核依赖该行为的批量方案；调度 reviewer 同步调整前置条件。只复核受影响链路，证据仍缺则保留未决，不无限辩论。
-3. 按根因与修订动作去重，保留所有实质不同的问题；多处症状归并后仍附关键定位。不设问题数量指标，也不只报前三项。误报撤回，低证据主张移到待核实项，不凑 P3。
-4. 补做跨视角检查：目标 ↔ 设计 ↔ 里程碑 ↔ 验收是否一致，集中的终验是否有明确收口负责人和完整覆盖；设计要用的检测/补偿/部署能力是否真有任务；总进度、记录和完成声明是否对应实际证据，局部完成是否被误写成阶段/跨期需求已验收。
-5. 若 `dev-plan` 校验脚本可用且适用，用实际路径运行 `check_paths.sh <计划> <仓库根>` 与 `check_progress.sh <计划> <仓库根>`。路径缺失须人工区分新增、示例、错误复用。用户自定义模板或历史计划未采用该恢复快照/完成记录协议时，跳过 `check_progress.sh` 并说明原因，人工核对其等价进度、依赖与验收证据；不要把格式不兼容判成计划错误。脚本通过不证明行为真实或验收完成；脚本缺失/失败如实记录，不用“通过”替代人工检查。
-6. 结束前核对计划及相关代码有无并发修改。若基线变化，只重审受影响结论；无法收敛则标为待核实。收集或停止尚在运行的 reviewer，再交付。
+```formal
+WORKFLOW @plan_adjudication:
+  DO: ["收齐四视角结果，逐条读候选问题的计划段落与原始证据，确认范围/版本/触发，reviewer 一致不等于事实",
+       "对事实冲突、方案依赖和交付断点向关联视角追问并同步前置，仅复核受影响链路；缺证留未决，不无限辩论",
+       "按根因及修订动作去重，保留所有实质问题及关键定位，不设数量指标、不只报前三项；撤回误报，低证据主张待核实，不凑 P3",
+       "核对目标 ↔ 设计 ↔ 里程碑 ↔ 验收，集中终验有收口负责人及完整覆盖，检测/补偿/部署能力有任务，进度/记录/完成声明有证据，局部完成不冒充阶段或跨期终验",
+       "按 @plan_script_checks 执行适用校验并人工核对等价证据",
+       "交付前核对计划/代码并发变化，只重审受影响结论，无法收敛标待核实；收集或停止仍运行的 reviewer"]
+
+RULE @plan_script_checks:
+  MUST: ["dev-plan 脚本可用且适用时，以实际路径运行 check_paths.sh <计划> <仓库根> 与 check_progress.sh <计划> <仓库根>；缺失路径人工区分新增、示例和错误复用",
+         "自定义/历史计划未采用恢复快照/完成记录协议时，说明原因并跳过 check_progress.sh，人工核对等价进度、依赖与验收证据，不因格式不兼容判错",
+         "脚本通过不证明行为真实或验收完成；脚本缺失/失败据实记录，不用通过替代人工检查"]
+```
 
 ## 4. 输出评审结果
 
-使用 [references/report-contract.md](references/report-contract.md) 的报告结构和落盘合同：**先列问题，再给结论与修订顺序**。由主 agent 写入完整报告；空 findings 或建议状态为 `Blocked` 也要落盘，不能只保存摘要或子 agent 回报。
+使用 [报告合同](references/report-contract.md) 的完整顺序与字段：先问题，后结论和修订顺序。报告头引用原计划，保留四维覆盖、证据等级、映射、依赖/并行与集成安排；没有安全并行空间时说明具体原因。
 
-报告至少包含：
+```formal
+WORKFLOW @plan_report_delivery:
+  DO: ["主 agent 单写完整报告，空 findings 或 Blocked 也按 @plan_default_delivery 处理，不只保存摘要或 reviewer 回报",
+       =>[report_saved, "回读实际文件，沿评审对象链接核对原计划身份/版本/范围及实际报告目录下的相对路径，检查全部字段和链接"],
+       "按第 5 节给是否需要修改与下一步；已保存则给实际链接、建议状态及关键摘要，仅聊天则交完整报告，保存失败按 @plan_report_failure 交付未完成结果"]
 
-- 报告头的「评审对象」：原开发计划的可点击引用、类型、所审版本与范围；本地路径相对实际报告目录，回读时核验，使 `apply-doc-review` 可仅接收报告参数。
-- 按严重度排序、编号的问题，每条定位到计划行或稳定章节，并附行为级代码/规则/外部证据。
-- 四个维度的审查覆盖及未核实项；UI 分清文档推演、原型走查和实际浏览器验证。
-- 需求到交付的映射缺口，以及建议的依赖顺序、可并行任务、共享资源负责人和最终集成验收。没有安全并行空间时给出具体原因。
-- 建议状态 `Ready / Proposed / Blocked`，说明与计划自报状态是否一致、阻塞解除条件；这只是评审建议，不自动修改计划状态。
+RULE @plan_report_limits:
+  MUST: "Ready / Proposed / Blocked 是评审建议，与自报状态分记并说明差异/阻塞解除条件，不自动改计划；通过不表示已实现或上线可用"
+  MUST_NOT: "因没有确认 findings 就在关键前提未核实时判 Ready"
 
-**没有确认问题时允许空 findings；有未核实的关键前提时不能据此判 Ready。计划评审通过也不表示功能已实现或上线可用。**
+RULE @plan_report_failure:
+  WHEN: report_write_tool_unavailable_or_write_failed
+  MUST: "明确报告未落盘、原因与目标路径，聊天保留完整报告，将保存标未完成，不链接不存在产物或用摘要冒充完成"
 
-交付前确认：报告已写入并回读、内容符合上述合同、文件链接指向实际产物。最终回复给出报告链接、建议状态及关键问题/待核实项摘要；用户明确要求仅聊天时，直接在聊天中交付完整报告。写入失败时按落盘合同说明未完成项，不把聊天摘要算作完成。
+REVIEW:
+  CHECK: [@plan_default_delivery, @plan_review_scope, @plan_claim_evidence,
+          @plan_re_review, @plan_review_scheduling, @plan_review_resources, @plan_adjudication,
+          @plan_script_checks, @plan_report_delivery, @plan_report_limits, @plan_report_failure]
+  ALSO: ["报告合同字段齐全，四维覆盖无遗漏；文档/原型/浏览器证据等级如实；不强加不适用的新版格式或重复验收"]
+  EXPOSE: on_issue
+```
 
 ## 5. 是否需要修改与下一步
 

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

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