@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/templates/.agents/skills/review-code/reference/report-template.zh-CN.md

@@ -21,11 +21,50 @@
 - **审查者**：{reviewer-name}
 - **审查时间**：{timestamp}
 - **审查范围**：{file-count and major modules}
-- **审查基线提交**：{本轮一次性捕获的 R 原文}（仅表示 diff base；详见 `.agents/rules/review-handshake.md`）
+- **审查基线提交**：{本轮一次性捕获的审查提交 R 原文；必须等于本轮 HEAD}
+- **审查差异基线**：{用于完整 diff/fingerprint 的 D 原文；已绑定 PR 时为 R 与 PR base SHA 的 merge-base，否则为 R}
 - **审查差异指纹**：{git-workflow snapshot 输出的 fingerprint 字段}
 - **审查快照树**：{git-workflow snapshot 输出的 tree 字段}
 - **总体结论**：{通过 / 需要修改 / 拒绝}（恰取一个；禁止写组合短语，否则 verify gate 失败）
-- **发现（AI 可处理）**：0 阻塞项，0 主要，0 次要 / **人工校验**：0
+- **发现（AI 可处理）**：{unresolved-blockers} 阻塞项，{unresolved-major} 主要，{unresolved-minor} 次要 / **人工校验**：0
+
+## 检视覆盖声明
+
+| pass_id | scope | evidence | result | gaps_or_assumptions |
+|---------|-------|----------|--------|---------------------|
+| pass-1..5 | {本遍实际范围} | {artifact / diff / file:line / command} | {发现或结论} | {缺口或假设} |
+
+| lens_id | trigger_evidence | loaded | result |
+|---------|------------------|--------|--------|
+| {registry token} | {命中或未命中证据} | {yes / no / not-applicable} | {专项结论} |
+
+## 代码实现专项覆盖
+
+| context_id | changed_lines | related_context | uncovered_area | result_or_gap |
+|------------|---------------|-----------------|----------------|---------------|
+| {file/module} | {changed line ranges} | {callers/callees/state/data flow} | {not reviewed or none} | {result / gap} |
+
+| quality_id | applicability | evidence | result_or_gap |
+|------------|---------------|----------|---------------|
+| responsibility | {applicable / not-applicable} | {code or call evidence} | {result / gap} |
+| cohesion | {applicable / not-applicable} | {code or call evidence} | {result / gap} |
+| coupling | {applicable / not-applicable} | {dependency evidence} | {result / gap} |
+| dependency-direction | {applicable / not-applicable} | {dependency evidence} | {result / gap} |
+| abstraction-fit | {applicable / not-applicable} | {variation evidence} | {result / gap} |
+| pattern-cost | {applicable / not-applicable} | {problem, conditions, cost, simpler alternative} | {result / gap} |
+| change-locality | {applicable / not-applicable} | {change propagation evidence} | {result / gap} |
+| testability | {applicable / not-applicable} | {test seam or behavior evidence} | {result / gap} |
+| architecture-boundary | {applicable / not-applicable} | {approved plan boundary} | {result / gap} |
+
+| acceptance_id | plan_source | implementation_location | test_or_validation_evidence | status_or_gap |
+|---------------|-------------|-------------------------|-----------------------------|---------------|
+| {acceptance token} | {approved requirement/plan} | {file:line or diff} | {automated test / manual-validation / explicit gap} | {covered / gap} |
+
+## 追踪矩阵
+
+| source_id | upstream | reviewed_target | verification | status_or_gap |
+|-----------|----------|-----------------|--------------|---------------|
+| {需求/方案步骤} | {已批准需求或设计} | {代码 diff} | {自动化测试或人工校验} | {covered / gap} |
 
 ## 问题清单
 
@@ -33,15 +72,23 @@
 
 #### 1. {问题标题}
 **文件**：`{file-path}:{line-number}`
-**说明**：{details}
-**修复建议**：{fix suggestion}
+**场景**：{scenario}
+**影响**：{impact}
+**证据**：{evidence_type: test / call-chain / state-transition / data-flow / specification-conflict / file-location} — {reproducible evidence}
+**置信度**：{high / medium / low}
+**未验证假设**：{assumptions or none}
+**修复方向**：{fix direction}
 
 ### 主要问题（建议修复）
 
 #### 1. {问题标题}
 **文件**：`{file-path}:{line-number}`
-**说明**：{details}
-**修复建议**：{fix suggestion}
+**场景**：{scenario}
+**影响**：{impact}
+**证据**：{evidence_type: test / call-chain / state-transition / data-flow / specification-conflict / file-location} — {reproducible evidence}
+**置信度**：{high / medium / low}
+**未验证假设**：{assumptions or none}
+**修复方向**：{fix direction}
 
 ### 次要问题（低影响但需闭环）
 
@@ -75,7 +122,7 @@
 
 ## 证据原文
 
-> 每条“我验证了 X”断言都要配对对应 tool output 原文；gate 仅校验本段存在和至少一行 `$ `。每条 Blocker 必须配可复现命令（rg/grep/sed/nl）及其原文；无法复现的判断须降级或移入「自我质疑」。
+> 每条“我验证了 X”断言都要配对对应 tool output 原文；gate 仅校验本段存在和至少一行 `$ `。每条 Blocker 必须配可复现的测试、调用链、状态转换、数据流、规范冲突或准确位置证据；无法复现的判断须降级或移入「自我质疑」。
 
 - 断言：{verified claim}
 ```text

package/templates/.agents/skills/review-code/reference/review-criteria.en.md

@@ -13,10 +13,12 @@ Follow the `code-review` step in `.agents/workflows/feature-development.yaml`.
 - [ ] Error handling and edge cases
 - [ ] Performance and security risks
 - [ ] Comments and documentation
+  - [ ] New or changed documentation accurately reflects the current behavior after the change
+  - [ ] Documentation changes are deterministically routed to mandatory references by the shared risk-lens registry
 - [ ] Consistency with the approved technical plan
 - [ ] The reviewer checked whether the executor missed any key design decision that should be upgraded to `[needs-human-decision]`
 - [ ] Every `needs-human-decision` detail produced this round follows the self-contained structure in `.agents/rules/human-decision-context.md`
-- [ ] Every blocker is backed by reproducible grep/sed/nl evidence; conclusions not directly verified are declared under Self-Doubt
+- [ ] Every blocker/major uses semantic evidence proportionate to the issue; conclusions not directly verified are declared under Self-Doubt
 
 **Common anti-examples**:
 - Checking only whether tests pass without reading the actual diff
@@ -24,35 +26,38 @@ Follow the `code-review` step in `.agents/workflows/feature-development.yaml`.
 - Misclassifying environment-limited verification gaps as blockers
 - Asserting a `file:line` or behavior from memory or impression without verifying via rg/nl
 
-## Common Review Principles
+## Shared Method and Classification Boundary
 
-1. **Strict but fair**: identify issues and acknowledge solid work
-2. **Specific**: cite exact file paths and line numbers
-3. **Actionable**: suggest a concrete fix
-4. **Severity-based**: clearly distinguish blockers, major issues, and minor issues
+Read `.agents/rules/review-method.md` first and apply its five-pass protocol, risk lenses, and finding evidence contract. Finding, manual-validation, advisory, and `needs-human-decision` state semantics remain governed by `.agents/rules/review-handshake.md`. This file adds only code-stage criteria.
 
-## Three-category Decision Tree
+Also inspect `git diff`, the latest code artifact, latest technical-plan review artifact, and `task.md` Activity Log so the report reflects the full change context.
 
-1. A correctness, completeness, security, performance, test, or acceptance gap in the current implementation is a formal finding. Assign blocker / major / minor by impact; severity does not control closure, so minor findings must also reach a terminal state.
-2. When there is no known defect but validation requires a real environment, permission, or human operation, classify it as manual-validation.
-3. Only a future optimization that does not affect the current implementation's completeness, correctness, or acceptance is an advisory. Put it only in Non-blocking Advisories; do not add it to the ledger, finding counts, or verdict.
+## Five Code-stage Passes
 
-## Manual Validation Classification
+| pass_id | code-stage action |
+|---------|-------------------|
+| pass-1 | Read the complete diff, untracked files, implementation/plan artifacts, task source, and raw test results |
+| pass-2 | Map acceptance/plan → implementation → verification and record changed lines, call context, state/data flow, and uncovered areas |
+| pass-3 | Review overall design before per-file semantics; evaluate every shared registry trigger and read each matched reference in full |
+| pass-4 | Check guards, call constraints, test coverage, and narrower impact boundaries as counterevidence |
+| pass-5 | Reconcile findings, manual-validation, advisories, evidence types, unverified assumptions, ledger state, and verdict |
 
-Some findings cannot be closed by an AI agent in the current execution environment, for example:
+Line-by-line diff reading does not replace necessary call-chain, state-transition, or data-flow analysis.
 
-- Missing Docker / sandbox access for end-to-end validation
-- Missing a specific OS for macOS-only behavior
-- Missing third-party accounts / OAuth
-- Missing privileged operations such as root, sudo, or special network access
+## Structural Design Lenses
 
-**Decision tree**: "Can the AI agent close this item independently without changing the environment?"
-- Yes -> blocker / major / minor, based on risk
-- No -> **manual-validation** (a manual-validation meta-category, not part of severity ordering)
+| quality_id | review focus |
+|------------|--------------|
+| responsibility | Whether each module or function has a clear responsibility boundary |
+| cohesion | Whether behavior and data in one unit serve the same purpose |
+| coupling | Whether dependency count, knowledge leakage, and coordination cost are justified |
+| dependency-direction | Whether dependencies point toward approved stable boundaries |
+| abstraction-fit | Whether abstractions match real variation without being deficient or excessive |
+| pattern-cost | Whether the problem, applicability, cost, and simpler alternative justify a pattern |
+| change-locality | Whether one business change can remain local |
+| testability | Whether key behavior and failure paths can be observed and controlled reliably |
+| architecture-boundary | Whether implementation follows the approved architecture without reopening major selection during code review |
 
-Where manual-validation items go:
-- Record them in an independent review report section named "Manual Validation Items"
-- Record the done-note source field as `Manual-validation: 1`; `ai task log` normalizes it into review rows
-- Do **not** include them in the code-task fix loop; maintainers carry them in the PR description under manual verification
+## Evidence Types
 
-Also inspect `git diff`, the latest code artifact, latest technical-plan review artifact, and `task.md` Activity Log so the report reflects the full change context.
+Blocker/major evidence may use `test`, `call-chain`, `state-transition`, `data-flow`, `specification-conflict`, or `file-location`. Commands and `file:line` are location aids, not the only valid evidence; evidence must reproduce the scenario and explain its impact.

package/templates/.agents/skills/review-code/reference/review-criteria.zh-CN.md

@@ -13,10 +13,12 @@
 - [ ] 错误处理和边界情况
 - [ ] 性能与安全风险
 - [ ] 代码注释和文档
+  - [ ] 新增或修改的文档准确反映变更后的当前行为
+  - [ ] 文档变更由共享风险镜头注册表确定性路由到必读专项 reference
 - [ ] 与已批准技术方案的一致性
 - [ ] 已复核执行方是否漏标应升级为 `[needs-human-decision]` 的关键设计决策
 - [ ] 本轮所有 `needs-human-decision` 详情均符合 `.agents/rules/human-decision-context.md` 的自足结构
-- [ ] 每条 blocker 都配可复现的 grep/sed/nl 证据，未直接验证的结论已在「自我质疑」声明
+- [ ] 每条 blocker/major 都配与问题相称的语义证据，未直接验证的结论已在「自我质疑」声明
 
 **常见反例**：
 - 只检查测试是否通过，没有阅读实际 diff
@@ -24,35 +26,38 @@
 - 把环境缺失导致无法验证的事项误归类为 blocker
 - 凭印象或记忆断言 `file:line`/行为，没有用 rg/nl 复核就下结论
 
-## 通用审查原则
+## 共享方法与分类边界
 
-1. **严格但公正**：既要指出问题，也要承认做得好的部分
-2. **具体**：引用准确的文件路径和行号
-3. **可执行**：给出明确可落地的修复建议
-4. **按严重程度分类**：明确区分 blocker、major 和 minor
+先读取 `.agents/rules/review-method.md`，按其五遍协议、风险镜头和 finding 证据契约执行；finding、manual-validation、advisory 与 `needs-human-decision` 的状态语义以 `.agents/rules/review-handshake.md` 为准。本文件只补充代码实现阶段的专项判断。
 
-## 三类审查项决策树
+同时检查 `git diff`、最新实现产物、最新技术方案审查产物和 `task.md` Activity Log，确保报告反映完整的变更上下文。
 
-1. 若问题揭示当前实现或测试存在正确性、完整性、安全性、性能或验收缺口，登记为正式 finding，并按影响赋予 blocker / major / minor；severity 只表示影响大小，minor 也必须闭环。
-2. 若没有已知缺陷，但只能依赖真实环境、权限或人工操作完成验证，归为 manual-validation。
-3. 仅当建议属于未来优化且不影响当前实现的完整性、正确性和验收时，归为 advisory。advisory 只写入「非阻塞建议」，不进入账本、问题计数或 verdict。
+## 代码阶段五遍动作
 
-## 人工校验项分类
+| pass_id | code-stage action |
+|---------|-------------------|
+| pass-1 | 读取完整 diff、未跟踪文件、实现/方案产物、任务来源和测试原始结果 |
+| pass-2 | 建立验收/方案—实现—验证映射，并记录 changed lines、调用上下文、状态/数据流和未覆盖区域 |
+| pass-3 | 先检查整体设计，再检查逐文件语义；判断共享注册表的每个触发器并完整加载命中 reference |
+| pass-4 | 检查保护条件、调用约束、测试覆盖和更窄影响范围等反证 |
+| pass-5 | 核对 finding、manual-validation、advisory、证据类型、未验证假设、账本和 verdict |
 
-某些发现项是 AI agent 在本执行环境**无法闭环**的，例如：
+逐行 diff 阅读不能替代必要的调用链、状态转换或数据流检查。
 
-- 缺 Docker / 沙箱而无法跑端到端验证
-- 缺特定 OS（macOS-only 行为）
-- 缺第三方账号 / OAuth
-- 缺特权操作（root、sudo、特殊网络）
+## 结构设计镜头
 
-**分类决策树**：「AI agent 能否在不改环境的前提下独立闭环这一项？」
-- 是 -> blocker / major / minor 之一（按风险定档）
-- 否 -> **manual-validation**（人工校验元类目，不参与严重程度排序）
+| quality_id | review focus |
+|------------|--------------|
+| responsibility | 单个模块或函数的职责边界是否清晰 |
+| cohesion | 同一单元内的行为和数据是否共同服务一个目的 |
+| coupling | 依赖数量、知识泄漏和跨模块协调成本是否合理 |
+| dependency-direction | 依赖是否指向已批准的稳定边界 |
+| abstraction-fit | 抽象是否匹配实际变化点，避免不足或过度抽象 |
+| pattern-cost | 模式解决的问题、适用条件、成本和更简单替代是否相称 |
+| change-locality | 同一业务变化是否能局部完成 |
+| testability | 关键行为和失败路径能否被可靠观察与控制 |
+| architecture-boundary | 实现是否遵守已批准架构，不在代码审查阶段首次重选重大架构 |
 
-manual-validation 项的去向：
-- 写入 review 报告独立段落「人工校验项」
-- 在 done note 中写入源字段 `Manual-validation: 1`；`ai task log` 归一化展示到 review 行
-- **不**进入 code-task 修复循环；维护者在 PR description 中以「待人工验证」清单形式承接
+## 证据类型
 
-同时检查 `git diff`、最新实现产物、最新技术方案审查产物和 `task.md` Activity Log，确保报告反映完整的变更上下文。
+blocker/major 可使用 `test`、`call-chain`、`state-transition`、`data-flow`、`specification-conflict` 或 `file-location`。命令和 `file:line` 是定位手段，不是唯一有效证据；证据必须能复现问题场景并解释影响。

package/templates/.agents/skills/review-code/reference/security-risks.en.md

@@ -0,0 +1,25 @@
+# Security Risk Review
+
+## Scope
+
+Use when changes touch authentication, authorization, untrusted input, sensitive data, credentials, cryptography, dependencies, or system boundaries.
+
+## Review Questions
+
+- Are trust boundaries, permission checks, and deny-by-default behavior explicit?
+- Do input validation, output encoding, secret handling, and logging avoid expanding exposure?
+- Do new dependencies or system calls introduce capabilities or supply-chain risks outside the approved plan?
+
+## Evidence Requirements
+
+Trace the call chain or data flow from entry through validation, authorization, use, and failure exits. Support conclusions with tests, specification conflicts, or accurate locations.
+
+## Common Counterexamples
+
+- Assuming safety merely because a security-related API is used.
+- Checking only the happy path while ignoring bypasses and failure defaults.
+- Treating unavailable real credentials or external systems as blockers by default.
+
+## When Closure Is Not Possible
+
+Record reproducible defects as findings, checks requiring real permissions or external systems as manual-validation, and unsupported uncovered boundaries as a gap. Do not approve unconditionally.

package/templates/.agents/skills/review-code/reference/security-risks.zh-CN.md

@@ -0,0 +1,25 @@
+# 安全风险检视
+
+## 适用范围
+
+当变更触及认证授权、非可信输入、敏感数据、凭据、加密、依赖或系统边界时使用。
+
+## 检视问题
+
+- 信任边界、权限检查和默认拒绝行为是否保持清晰。
+- 输入验证、输出编码、秘密处理和日志记录是否避免扩大暴露面。
+- 新依赖或系统调用是否引入未被方案覆盖的能力或供应链风险。
+
+## 证据要求
+
+沿入口、校验、授权、数据使用和失败出口记录调用链或数据流；用测试、规范冲突或准确位置支撑结论。
+
+## 常见反例
+
+- 仅因使用了安全相关 API 就判定安全。
+- 只检查正常路径，不检查绕过路径和失败默认值。
+- 把无法访问真实凭据或外部系统直接归为 blocker。
+
+## 无法闭环时
+
+可复现缺陷形成 finding；必须在真实权限或外部系统中执行的检查进入 manual-validation；证据不足的未覆盖边界记录为 gap，不得无条件通过。

package/templates/.agents/skills/review-plan/SKILL.en.md

@@ -55,6 +55,7 @@ Read `{plan-artifact}`, the latest analysis artifact, `task.md`, and Issue conte
 
 Check simplicity, executability, risk control, test strategy, file coverage, and phase boundaries.
 
+> Read `.agents/rules/review-method.md` before this step and follow its five-pass protocol for coverage, risk-lens decisions, traceability, and counterevidence.
 > Read `reference/review-criteria.md` before this step.
 
 ### 5. Write Review Report
@@ -65,7 +66,17 @@ Create `.agents/workspace/active/{task-id}/{review-artifact}`.
 
 ### 6. Update Task Status
 
-After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, call `agent-infra-internal task-ledger {task-id} stage-status --stage plan` exactly once. Derive the verdict and next-step branch from `stageStatus.canAdvance`, and blocker/major/minor event counts from `unresolvedFindingCounts`: only `canAdvance=true` permits `approved`; otherwise use `changes-requested` or `rejected`. Then run `agent-infra-internal task-event {task-id} review-plan.completed --agent {agent} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {n} --major {n} --minor {n} --manual-validation {n}`.
+After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, call `agent-infra-internal task-review {task-id} finalize-summary --stage plan --artifact {review-artifact}` exactly once.
+
+Bind and reuse this structured mapping from that one response:
+
+```text
+{unresolved-blockers} = stageStatus.unresolvedFindingCounts.blocker
+{unresolved-major} = stageStatus.unresolvedFindingCounts.major
+{unresolved-minor} = stageStatus.unresolvedFindingCounts.minor
+```
+
+The intent atomically finalizes the report summary and returns the same ledger snapshot. Do not call `stage-status`, replace placeholders manually, or rescan the finding list. If finalization fails or a response field is missing, stop before the completion event. Derive the verdict and next-step branch from the same response's `stageStatus.canAdvance`: only `canAdvance=true` permits `approved`; otherwise use `changes-requested` or `rejected`. Then run `agent-infra-internal task-event {task-id} review-plan.completed --agent {agent} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {unresolved-blockers} --major {unresolved-major} --minor {unresolved-minor} --manual-validation {n}`.
 
 `manual-validation` is the data source for the `Manual-validation` count folded into review rows in `ai task log`; do not add a parallel manual-verification field.
 
@@ -79,6 +90,6 @@ agent-infra-internal task-verify {task-id} review-plan.completed --artifact {rev
 
 ### 8. Tell the User
 
-Use the conclusion branch in `reference/output-templates.md` and show all TUI command formats.
+Use the conclusion branch in `reference/output-templates.md` and render the selected next-step commands through the shared helper.
 
 > Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the current task's short id `NN` (see that file for lookup and fallback), while other `{task-id}` placeholders (report titles, paths) keep the full TASK-id form; (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).

package/templates/.agents/skills/review-plan/SKILL.zh-CN.md

@@ -58,6 +58,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 重点检查方案的简洁性、可执行性、风险控制、测试策略、文件清单和阶段边界。
 
+> 共享检视方法见 `.agents/rules/review-method.md`。执行此步骤前先读取该规则，并按五遍协议完成覆盖声明、风险镜头判断、追踪矩阵和反证检视。
 > 详细审查标准见 `reference/review-criteria.md`。执行此步骤前先读取 `reference/review-criteria.md`。
 
 ### 5. 编写审查报告
@@ -68,7 +69,17 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 ### 6. 更新任务状态
 
-报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后只调用一次 `agent-infra-internal task-ledger {task-id} stage-status --stage plan`，以 `stageStatus.canAdvance` 决定 verdict 和下一步，并以 `unresolvedFindingCounts` 填写 blocker/major/minor：仅 `canAdvance=true` 可用 `approved`，否则必须用 `changes-requested` 或 `rejected`。随后执行 `agent-infra-internal task-event {task-id} review-plan.completed --agent {agent} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {n} --major {n} --minor {n} --manual-validation {n}`。
+报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage plan --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后只调用一次 `agent-infra-internal task-review {task-id} finalize-summary --stage plan --artifact {review-artifact}`。
+
+从该次返回值绑定并复用以下结构化映射：
+
+```text
+{unresolved-blockers} = stageStatus.unresolvedFindingCounts.blocker
+{unresolved-major} = stageStatus.unresolvedFindingCounts.major
+{unresolved-minor} = stageStatus.unresolvedFindingCounts.minor
+```
+
+该 intent 原子最终化报告摘要并返回同一次账本快照；不得再调用 `stage-status`、手工替换占位符或扫描问题清单。最终化失败或返回字段缺失时，停止在完成事件之前。以同一次返回的 `stageStatus.canAdvance` 决定 verdict 和下一步：仅 `canAdvance=true` 可用 `approved`，否则必须用 `changes-requested` 或 `rejected`。随后执行 `agent-infra-internal task-event {task-id} review-plan.completed --agent {agent} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {unresolved-blockers} --major {unresolved-major} --minor {unresolved-minor} --manual-validation {n}`。
 
 `manual-validation` 是 `ai task log` 中 review 行「人工校验点」（EN `Manual-validation`）计数的数据源；不要新增并行人工验证字段。
 
@@ -84,7 +95,7 @@ agent-infra-internal task-verify {task-id} review-plan.completed --artifact {rev
 
 ### 8. 告知用户
 
-按 `reference/output-templates.md` 的结论分支输出，并展示所有 TUI 的下一步命令。
+按 `reference/output-templates.md` 的结论分支输出，并通过统一 helper 渲染已选场景的下一步命令。
 
 > 渲染最终输出前先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令的 `{task-ref}` 渲染为当前任务短号 `NN`（取值与回退见该文件），其他 `{task-id}` 占位（报告标题、路径）保持完整 TASK-id 形式；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
@@ -93,7 +104,7 @@ agent-infra-internal task-verify {task-id} review-plan.completed --artifact {rev
 - [ ] 已审查最新方案上下文
 - [ ] 已创建 `{review-artifact}`
 - [ ] 已更新 task.md 并追加 Activity Log
-- [ ] 已展示所有 TUI 的下一步命令
+- [ ] 已通过统一 helper 渲染已选场景的下一步命令
 
 ## 注意事项
 

package/templates/.agents/skills/review-plan/config/verify.en.json

@@ -19,6 +19,9 @@
       "file_pattern": "review-plan.md|review-plan-r{N}.md",
       "required_sections": [
         "Review Summary",
+        "Review Coverage Declaration",
+        "Technical Plan Architecture Coverage",
+        "Traceability Matrix",
         "Findings",
         "Non-blocking Advisories",
         "Manual Validation Items",
@@ -33,6 +36,9 @@
         "^\\$ "
       ]
     },
+    "review-summary": {
+      "stage": "plan"
+    },
     "activity-log": {
       "expected_action_pattern": "(Review Plan|Plan Review) \\(Round \\d+\\)"
     },

package/templates/.agents/skills/review-plan/config/verify.zh-CN.json

@@ -19,6 +19,9 @@
       "file_pattern": "review-plan.md|review-plan-r{N}.md",
       "required_sections": [
         "审查摘要",
+        "检视覆盖声明",
+        "技术方案架构覆盖",
+        "追踪矩阵",
         "问题清单",
         "非阻塞建议",
         "人工校验项",
@@ -33,6 +36,9 @@
         "^\\$ "
       ]
     },
+    "review-summary": {
+      "stage": "plan"
+    },
     "activity-log": {
       "expected_action_pattern": "(Review Plan|Plan Review) \\(Round \\d+\\)"
     },

package/templates/.agents/skills/review-plan/reference/output-templates.en.md

@@ -15,22 +15,20 @@ Rules:
 - Do not mix text from multiple scenarios
 - If `Blocker > 0`, never use an approved template
 - Never count manual-validation items as blocker / major / minor or use them to trigger Scenario B/C/D
-- The selected scenario must include all TUI command formats
+- The selected scenario must generate `{next-step-commands}` through the shared helper
 - The count line shows 4 numbers. `Human-decision` (`{h}`) counts this stage's `needs-human-decision` rows; because those rows are unresolved, `{h} > 0` means `canAdvance=false`. Expand the "Pending human-decision pre-block" from `.agents/rules/next-step-output.md` and show revision and re-review paths only.
 
-For Scenarios B/C/D, follow the revision commands with re-review commands: `/review-plan {task-ref}`, `/{{project}}:review-plan {task-ref}`, and `$review-plan {task-ref}`.
-
 ### Scenario A: Approved with no findings
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill code-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} technical plan review completed. Verdict: approved.
 - Blockers: 0 | Major issues: 0 | Minor issues: 0 | Human-decision: {h}
 [- Review report: .agents/workspace/active/{task-id}/{review-artifact}]
 
 Next step - write code:
-  - Claude Code / OpenCode: /code-task {task-ref}
-  - Gemini CLI: /{{project}}:code-task {task-ref}
-  - Codex CLI: $code-task {task-ref}
+{next-step-commands}
 
 [When manual-validation > 0, append:]
 Reminder: manual-validation items belong in the PR description manual verification checklist and should not trigger /plan-task.
@@ -38,15 +36,15 @@ Reminder: manual-validation items belong in the PR description manual verificati
 
 ### Scenario B: Changes requested (major / minor)
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} technical plan review completed. Verdict: changes requested.
 - Blockers: 0 | Major issues: {n} | Minor issues: {n} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - revise technical plan:
-  - Claude Code / OpenCode: /plan-task {task-ref}
-  - Gemini CLI: /{{project}}:plan-task {task-ref}
-  - Codex CLI: $plan-task {task-ref}
+{next-step-commands}
 
 [When manual-validation > 0, append:]
 Reminder: manual-validation items belong in the PR description manual verification checklist and should not trigger /plan-task.
@@ -54,15 +52,15 @@ Reminder: manual-validation items belong in the PR description manual verificati
 
 ### Scenario C: Changes requested
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} technical plan review completed. Verdict: changes requested.
 - Blockers: {n} | Major issues: {n} | Minor issues: {n} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - revise technical plan:
-  - Claude Code / OpenCode: /plan-task {task-ref}
-  - Gemini CLI: /{{project}}:plan-task {task-ref}
-  - Codex CLI: $plan-task {task-ref}
+{next-step-commands}
 
 [When manual-validation > 0, append:]
 Reminder: manual-validation items belong in the PR description manual verification checklist and should not trigger /plan-task.
@@ -70,15 +68,15 @@ Reminder: manual-validation items belong in the PR description manual verificati
 
 ### Scenario D: Rejected
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} technical plan review completed. Verdict: rejected, redesign required.
 - Blockers: {n} | Major issues: {n} | Minor issues: {n} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - redesign:
-  - Claude Code / OpenCode: /plan-task {task-ref}
-  - Gemini CLI: /{{project}}:plan-task {task-ref}
-  - Codex CLI: $plan-task {task-ref}
+{next-step-commands}
 
 [When manual-validation > 0, append:]
 Reminder: manual-validation items belong in the PR description manual verification checklist and should not trigger /plan-task.

package/templates/.agents/skills/review-plan/reference/output-templates.zh-CN.md

@@ -15,22 +15,20 @@
 - 不要混用不同场景的文案
 - 只要 `Blocker > 0`，就绝对不能输出通过模板
 - manual-validation 项绝对不能被计入 blocker / major / minor 计数，也不能用作触发场景 B/C/D 的依据
-- 所选场景中必须包含所有 TUI 命令格式
+- 所选场景必须通过统一 helper 生成 `{next-step-commands}`
 - 计数行固定显示 4 个数字。`人工裁决`（`{h}`）是本阶段 `needs-human-decision` 行数；它属于未闭环账本状态，因此 `{h} > 0` 时 `canAdvance=false`，必须按 `.agents/rules/next-step-output.md` 的「人工裁决待办前置块」展开详情，并只输出修订与复审路径。
 
-场景 B/C/D 在修订命令后继续列出复审命令：`/review-plan {task-ref}`、`/{{project}}:review-plan {task-ref}`、`$review-plan {task-ref}`。
-
 ### 场景 A：通过且无问题
 
+使用 `agent-infra-internal agent-client next-steps --skill code-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```text
 任务 {task-id} 技术方案审查完成。结论：通过。
 - 阻塞项：0 | 主要问题：0 | 次要问题：0 | 人工裁决：{h}
 [- 审查报告：.agents/workspace/active/{task-id}/{review-artifact}]
 
 下一步 - 编写代码：
-  - Claude Code / OpenCode：/code-task {task-ref}
-  - Gemini CLI：/{{project}}:code-task {task-ref}
-  - Codex CLI：$code-task {task-ref}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
@@ -38,15 +36,15 @@
 
 ### 场景 B：需要修改（major / minor）
 
+使用 `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```text
 任务 {task-id} 技术方案审查完成。结论：需要修改。
 - 阻塞项：0 | 主要问题：{n} | 次要问题：{n} | 人工裁决：{h}
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 修订技术方案：
-  - Claude Code / OpenCode：/plan-task {task-ref}
-  - Gemini CLI：/{{project}}:plan-task {task-ref}
-  - Codex CLI：$plan-task {task-ref}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
@@ -54,15 +52,15 @@
 
 ### 场景 C：需要修改
 
+使用 `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```text
 任务 {task-id} 技术方案审查完成。结论：需要修改。
 - 阻塞项：{n} | 主要问题：{n} | 次要问题：{n} | 人工裁决：{h}
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 修订技术方案：
-  - Claude Code / OpenCode：/plan-task {task-ref}
-  - Gemini CLI：/{{project}}:plan-task {task-ref}
-  - Codex CLI：$plan-task {task-ref}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
@@ -70,15 +68,15 @@
 
 ### 场景 D：拒绝
 
+使用 `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+
 ```text
 任务 {task-id} 技术方案审查完成。结论：拒绝，需要重新设计。
 - 阻塞项：{n} | 主要问题：{n} | 次要问题：{n} | 人工裁决：{h}
 - 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
 
 下一步 - 重新设计：
-  - Claude Code / OpenCode：/plan-task {task-ref}
-  - Gemini CLI：/{{project}}:plan-task {task-ref}
-  - Codex CLI：$plan-task {task-ref}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。