@fitlab-ai/agent-infra 0.9.1 → 0.9.2

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

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

package/templates/.agents/skills/review-analysis/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-analysis {task-ref}`, `/{{project}}:review-analysis {task-ref}`, and `$review-analysis {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 plan-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} requirement analysis 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 the 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 /analyze-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 analyze-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} requirement analysis 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 requirement analysis:
-  - Claude Code / OpenCode: /analyze-task {task-ref}
-  - Gemini CLI: /{{project}}:analyze-task {task-ref}
-  - Codex CLI: $analyze-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 /analyze-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 analyze-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} requirement analysis 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 requirement analysis:
-  - Claude Code / OpenCode: /analyze-task {task-ref}
-  - Gemini CLI: /{{project}}:analyze-task {task-ref}
-  - Codex CLI: $analyze-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 /analyze-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 analyze-task --task-ref {task-ref}`.
+
 ```text
 Task {task-id} requirement analysis review completed. Verdict: rejected, fresh analysis or requirement clarification required.
 - Blockers: {n} | Major issues: {n} | Minor issues: {n} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - re-analyze:
-  - Claude Code / OpenCode: /analyze-task {task-ref}
-  - Gemini CLI: /{{project}}:analyze-task {task-ref}
-  - Codex CLI: $analyze-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 /analyze-task.

package/templates/.agents/skills/review-analysis/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-analysis {task-ref}`、`/{{project}}:review-analysis {task-ref}`、`$review-analysis {task-ref}`。
-
 ### 场景 A：通过且无问题
 
+使用 `agent-infra-internal agent-client next-steps --skill plan-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：/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 的「待人工验证」清单中承接，不应触发 /analyze-task。
@@ -38,15 +36,15 @@
 
 ### 场景 B：需要修改（major / minor）
 
+使用 `agent-infra-internal agent-client next-steps --skill analyze-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：/analyze-task {task-ref}
-  - Gemini CLI：/{{project}}:analyze-task {task-ref}
-  - Codex CLI：$analyze-task {task-ref}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /analyze-task。
@@ -54,15 +52,15 @@
 
 ### 场景 C：需要修改
 
+使用 `agent-infra-internal agent-client next-steps --skill analyze-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：/analyze-task {task-ref}
-  - Gemini CLI：/{{project}}:analyze-task {task-ref}
-  - Codex CLI：$analyze-task {task-ref}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /analyze-task。
@@ -70,15 +68,15 @@
 
 ### 场景 D：拒绝
 
+使用 `agent-infra-internal agent-client next-steps --skill analyze-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：/analyze-task {task-ref}
-  - Gemini CLI：/{{project}}:analyze-task {task-ref}
-  - Codex CLI：$analyze-task {task-ref}
+{next-step-commands}
 
 [当 manual-validation > 0 时，在最后附加一行：]
 提醒：manual-validation 项需在 PR description 的「待人工验证」清单中承接，不应触发 /analyze-task。

package/templates/.agents/skills/review-analysis/reference/report-template.en.md

@@ -22,7 +22,45 @@ Use this template when writing `review-analysis.md` or `review-analysis-r{N}.md`
 - **Review Time**: {timestamp}
 - **Scope**: {file-count and major modules}
 - **Overall Verdict**: {Approved / Changes Requested / Rejected}
-- **Findings (AI-actionable)**: 0 blockers, 0 majors, 0 minors / **Manual validation**: 0
+- **Findings (AI-actionable)**: {unresolved-blockers} blockers, {unresolved-major} majors, {unresolved-minor} minors / **Manual validation**: 0
+
+## Review Coverage Declaration
+
+| pass_id | scope | evidence | result | gaps_or_assumptions |
+|---------|-------|----------|--------|---------------------|
+| pass-1..5 | {scope actually reviewed} | {artifact / file:line / command} | {finding or conclusion} | {gap or assumption} |
+
+| lens_id | trigger_evidence | loaded | result |
+|---------|------------------|--------|--------|
+| {registry token} | {trigger or non-trigger evidence} | {yes / no / not-applicable} | {lens result} |
+
+## Requirement Analysis Coverage
+
+| perspective_id | applicability | reviewed_scope | evidence | result_or_gap |
+|----------------|---------------|----------------|----------|---------------|
+| user | {applicable / not-applicable} | {business goals, user outcomes, non-goals, and acceptance} | {source_id / artifact / file:line} | {covered / gap} |
+| maintainer | {applicable / not-applicable} | {maintenance boundaries, dependencies, compatibility, and ownership} | {source_id / artifact / file:line} | {covered / gap} |
+| operations | {applicable / not-applicable} | {deployment, runtime, observability, recovery, and support constraints} | {source_id / artifact / file:line} | {covered / gap} |
+| security | {applicable / not-applicable} | {trust boundaries, permissions, data, and abuse risks} | {source_id / artifact / file:line} | {covered / gap} |
+| testing | {applicable / not-applicable} | {inputs, actions, results, boundaries, and verification environment} | {source_id / artifact / file:line} | {covered / gap} |
+
+| quality_id | source | stakeholder | priority_or_tradeoff | verification | result_or_gap |
+|------------|--------|-------------|----------------------|--------------|---------------|
+| {stable identifier} | {source_id} | {stakeholder} | {priority or trade-off state} | {observable verification} | {covered / gap} |
+
+| evolution_id | source | confirmation_status | classification | boundary_evidence | result_or_gap |
+|--------------|--------|---------------------|----------------|-------------------|---------------|
+| {stable identifier} | {source_id} | {confirmed / unconfirmed} | {design-input / assumption / open-question} | {evidence preventing current-scope expansion} | {covered / gap} |
+
+| acceptance_id | observable_input | action | expected_result | status_or_gap |
+|---------------|------------------|--------|-----------------|---------------|
+| {stable identifier} | {observable input} | {review or verification action} | {expected result} | {verifiable / open / gap} |
+
+## Traceability Matrix
+
+| source_id | upstream | reviewed_target | verification | status_or_gap |
+|-----------|----------|-----------------|--------------|---------------|
+| {source identifier} | {upstream requirement or fact} | {requirement/acceptance/impact/risk} | {verification evidence} | {covered / gap} |
 
 ## Findings
 
@@ -30,15 +68,23 @@ Use this template when writing `review-analysis.md` or `review-analysis-r{N}.md`
 
 #### 1. {Issue title}
 **File**: `{file-path}:{line-number}`
-**Description**: {details}
-**Suggested Fix**: {fix suggestion}
+**Scenario**: {scenario}
+**Impact**: {impact}
+**Evidence**: {reproducible evidence}
+**Confidence**: {high / medium / low}
+**Unverified Assumptions**: {assumptions or none}
+**Fix Direction**: {fix direction}
 
 ### Major Issues (should fix)
 
 #### 1. {Issue title}
 **File**: `{file-path}:{line-number}`
-**Description**: {details}
-**Suggested Fix**: {fix suggestion}
+**Scenario**: {scenario}
+**Impact**: {impact}
+**Evidence**: {reproducible evidence}
+**Confidence**: {high / medium / low}
+**Unverified Assumptions**: {assumptions or none}
+**Fix Direction**: {fix direction}
 
 ### Minor Issues (low impact, closure required)
 

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

@@ -5,7 +5,7 @@
 ## 输出模板
 
 ```markdown
-# 代码审查报告
+# 需求分析审查报告
 
 - **审查轮次**：第 {review-round} 轮
 - **产物文件**：`{review-artifact}`
@@ -22,7 +22,45 @@
 - **审查时间**：{timestamp}
 - **审查范围**：{file-count and major modules}
 - **总体结论**：{通过 / 需要修改 / 拒绝}
-- **发现（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 / file:line / command} | {发现或结论} | {缺口或假设} |
+
+| lens_id | trigger_evidence | loaded | result |
+|---------|------------------|--------|--------|
+| {registry token} | {命中或未命中证据} | {yes / no / not-applicable} | {专项结论} |
+
+## 需求分析专项覆盖
+
+| perspective_id | applicability | reviewed_scope | evidence | result_or_gap |
+|----------------|---------------|----------------|----------|---------------|
+| user | {applicable / not-applicable} | {业务目标、使用结果、非目标与验收} | {source_id / artifact / file:line} | {covered / gap} |
+| maintainer | {applicable / not-applicable} | {维护边界、依赖、兼容性与长期责任} | {source_id / artifact / file:line} | {covered / gap} |
+| operations | {applicable / not-applicable} | {部署、运行、可观测性、恢复与支持约束} | {source_id / artifact / file:line} | {covered / gap} |
+| security | {applicable / not-applicable} | {信任边界、权限、数据与滥用风险} | {source_id / artifact / file:line} | {covered / gap} |
+| testing | {applicable / not-applicable} | {输入、动作、结果、边界与验证环境} | {source_id / artifact / file:line} | {covered / gap} |
+
+| quality_id | source | stakeholder | priority_or_tradeoff | verification | result_or_gap |
+|------------|--------|-------------|----------------------|--------------|---------------|
+| {稳定标识} | {source_id} | {利益相关者} | {优先级或权衡状态} | {可观察验证方式} | {covered / gap} |
+
+| evolution_id | source | confirmation_status | classification | boundary_evidence | result_or_gap |
+|--------------|--------|---------------------|----------------|-------------------|---------------|
+| {稳定标识} | {source_id} | {confirmed / unconfirmed} | {design-input / assumption / open-question} | {不扩张为当前需求的证据} | {covered / gap} |
+
+| acceptance_id | observable_input | action | expected_result | status_or_gap |
+|---------------|------------------|--------|-----------------|---------------|
+| {稳定标识} | {可观察输入} | {审查或验证动作} | {预期结果} | {verifiable / open / gap} |
+
+## 追踪矩阵
+
+| source_id | upstream | reviewed_target | verification | status_or_gap |
+|-----------|----------|-----------------|--------------|---------------|
+| {来源标识} | {上游需求或事实} | {需求/验收/影响/风险} | {验证证据} | {covered / gap} |
 
 ## 问题清单
 
@@ -30,15 +68,23 @@
 
 #### 1. {问题标题}
 **文件**：`{file-path}:{line-number}`
-**说明**：{details}
-**修复建议**：{fix suggestion}
+**场景**：{scenario}
+**影响**：{impact}
+**证据**：{reproducible evidence}
+**置信度**：{high / medium / low}
+**未验证假设**：{assumptions or none}
+**修复方向**：{fix direction}
 
 ### 主要问题（建议修复）
 
 #### 1. {问题标题}
 **文件**：`{file-path}:{line-number}`
-**说明**：{details}
-**修复建议**：{fix suggestion}
+**场景**：{scenario}
+**影响**：{impact}
+**证据**：{reproducible evidence}
+**置信度**：{high / medium / low}
+**未验证假设**：{assumptions or none}
+**修复方向**：{fix direction}
 
 ### 次要问题（低影响但需闭环）
 

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

@@ -23,35 +23,38 @@ Follow the `analysis-review` step in `.agents/workflows/feature-development.yaml
 - Presenting uncertain information as fact without marking assumptions or open questions
 - Asserting a `file:line` or behavior from memory or impression without verifying via rg/nl
 
-## Common Review Principles
+## Requirement Analysis Coverage
 
-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
+### Perspectives
 
-## Three-category Decision Tree
+Every review must examine these minimum perspectives and use their stable `perspective_id` values in the report:
 
-1. A gap in requirements, constraints, risks, affected scope, or verifiable acceptance criteria 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 analysis'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.
+- `user`: business goals, user outcomes, non-goals, and acceptance
+- `maintainer`: maintenance boundaries, dependencies, compatibility, and long-term ownership
+- `operations`: deployment, runtime, observability, recovery, and support constraints
+- `security`: trust boundaries, permissions, data, and abuse risks
+- `testing`: observable inputs, actions, results, boundary conditions, and verification environments
 
-## Manual Validation Classification
+For an applicable perspective, record the reviewed scope, evidence, and `covered/gap`. A `not-applicable` result requires reviewable evidence or it is a gap. Add stable tokens for other stakeholders triggered by task sources or risk evidence; do not turn every possible role into a fixed checklist.
 
-Some findings cannot be closed by an AI agent in the current execution environment, for example:
+### Quality Attributes
 
-- 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
+Record only quality attributes triggered by sources, constraints, or perspectives; do not impose a fixed vocabulary. Each item needs a stable `quality_id`, its source and stakeholder, a priority or trade-off state, a verifiable expression, and `covered/gap`. A candidate without a source may only be an assumption, open question, or non-blocking advisory, not a confirmed requirement.
 
-**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)
+### Evolution Scenarios
 
-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
+Each reasonable future change needs a stable `evolution_id`, source, `confirmed/unconfirmed` state, `design-input/assumption/open-question` classification, boundary evidence, and `covered/gap`. An `unconfirmed` scenario must not become a current requirement or directly drive an architecture or implementation choice.
+
+### Acceptance Criteria
+
+For every criterion, record a stable `acceptance_id`, observable input, review action, expected result, and `verifiable/open/gap`. A non-behavioral constraint may use an observable verification method instead of a behavioral step; anything that cannot close must become an open question or finding.
+
+### Traceability and Boundary
+
+The shared traceability matrix remains the only mapping from sources to analysis conclusions. Its `source_id` values should cover user requests, Issues, task facts and decisions, and acceptance criteria; stage-specific tables refer back through their source or evidence. This stage only judges whether analysis is ready for design. It does not select architecture styles, design patterns, or implementation technologies, and it does not duplicate the shared five-pass protocol or finding evidence fields.
+
+## Shared Method and Classification Boundary
+
+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 analysis-stage criteria.
 
 Also inspect the latest requirement analysis artifact and `task.md` Activity Log so the report reflects the full analysis context.

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

@@ -23,35 +23,38 @@
 - 对无法确认的信息直接下结论，没有标记假设或开放问题
 - 凭印象或记忆断言 `file:line`/行为，没有用 rg/nl 复核就下结论
 
-## 通用审查原则
+## 需求分析专项覆盖
 
-1. **严格但公正**：既要指出问题，也要承认做得好的部分
-2. **具体**：引用准确的文件路径和行号
-3. **可执行**：给出明确可落地的修复建议
-4. **按严重程度分类**：明确区分 blocker、major 和 minor
+### 角色视角
 
-## 三类审查项决策树
+每轮必须逐项检视以下最低视角，并在报告中使用稳定的 `perspective_id`：
 
-1. 若问题揭示当前需求分析缺少需求、约束、风险、影响范围或可验证验收标准，登记为正式 finding，并按影响赋予 blocker / major / minor；severity 只表示影响大小，minor 也必须闭环。
-2. 若没有已知缺陷，但只能依赖真实环境、权限或人工操作完成验证，归为 manual-validation。
-3. 仅当建议属于未来优化且不影响当前分析的完整性、正确性和验收时，归为 advisory。advisory 只写入「非阻塞建议」，不进入账本、问题计数或 verdict。
+- `user`：业务目标、使用结果、非目标和验收
+- `maintainer`：维护边界、依赖、兼容性和长期责任
+- `operations`：部署、运行、可观测性、恢复和支持约束
+- `security`：信任边界、权限、数据和滥用风险
+- `testing`：可观察的输入、动作、结果、边界条件和验证环境
 
-## 人工校验项分类
+适用视角记录实际范围、证据和 `covered/gap`；`not-applicable` 必须附可复核依据，否则视为 gap。若任务来源或风险证据出现其他利益相关者，追加稳定 token；不要把可能角色扩张成固定全集。
 
-某些发现项是 AI agent 在本执行环境**无法闭环**的，例如：
+### 质量属性
 
-- 缺 Docker / 沙箱而无法跑端到端验证
-- 缺特定 OS（macOS-only 行为）
-- 缺第三方账号 / OAuth
-- 缺特权操作（root、sudo、特殊网络）
+只记录由来源、约束或角色视角实际触发的质量属性，不使用固定名词全集。每项需有稳定 `quality_id`、来源与利益相关者、优先级或权衡状态、可验证表达及 `covered/gap`。缺少来源的候选项只能作为假设、开放问题或非阻塞建议，不能作为已确认需求。
 
-**分类决策树**：「AI agent 能否在不改环境的前提下独立闭环这一项？」
-- 是 -> blocker / major / minor 之一（按风险定档）
-- 否 -> **manual-validation**（人工校验元类目，不参与严重程度排序）
+### 演进场景
 
-manual-validation 项的去向：
-- 写入 review 报告独立段落「人工校验项」
-- 在 done note 中写入源字段 `Manual-validation: 1`；`ai task log` 归一化展示到 review 行
-- **不**进入 code-task 修复循环；维护者在 PR description 中以「待人工验证」清单形式承接
+合理未来变化需有稳定 `evolution_id`、来源、`confirmed/unconfirmed` 状态、`design-input/assumption/open-question` 分类、边界证据及 `covered/gap`。`unconfirmed` 场景不得升级为当前需求，也不得直接驱动架构或实现选择。
+
+### 验收标准
+
+逐项记录稳定 `acceptance_id`、可观察输入、审查动作、预期结果和 `verifiable/open/gap`。非行为型约束可用可观察验证方式替代行为步骤；无法闭环时必须进入开放问题或 finding。
+
+### 追踪与边界
+
+共享追踪矩阵仍是来源到分析结论的唯一映射。其 `source_id` 应覆盖用户请求、Issue、任务事实/决策和验收标准；专项表通过来源或证据回指这些稳定标识。本阶段只判断分析是否足以进入设计，不选择架构风格、设计模式或实现技术，也不复制共享五遍协议和 finding 证据字段。
+
+## 共享方法与分类边界
+
+先读取 `.agents/rules/review-method.md`，按其五遍协议、风险镜头和 finding 证据契约执行；finding、manual-validation、advisory 与 `needs-human-decision` 的状态语义以 `.agents/rules/review-handshake.md` 为准。本文件只补充需求分析阶段的专项判断。
 
 同时检查最新需求分析产物和 `task.md` Activity Log，确保报告反映完整的分析上下文。

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

@@ -67,13 +67,23 @@ Read the highest-round code artifact and, if present, the highest-round fix arti
 ### 4. Perform the Review
 
 Follow `.agents/workflows/feature-development.yaml` and inspect the full change context:
-- Capture `R=$(git rev-parse HEAD)` exactly once; reuse that R for this round's report, fingerprint, and task review fact, and do not re-read HEAD later as a substitute
-- `git diff --binary "$R" -- <post-review-globs>` for tracked changes
+- Capture the reviewed commit `R=$(git rev-parse HEAD)` exactly once; reuse R for this round's report, snapshot tree, and task review fact, and do not re-read HEAD later as a substitute
+- Call `agent-infra-internal platform-pr inspect {task-id}`. When a bound PR provides a base SHA, set the diff base to `D=$(git merge-base "$R" "{base-sha}")`. Without a PR, set `D=$R` only when tracked or untracked worktree changes exist. A clean worktree without a bound PR has no reliable complete committed range: stop and require a bound PR instead of reviewing an empty diff
+- `git diff --binary "$D" -- <post-review-globs>` covers committed and uncommitted tracked changes from D to the current worktree
 - `git ls-files -o --exclude-standard -z -- <post-review-globs>` for untracked new files
-- Write `mode=worktree` and baseline `R` to a temporary JSON file, then call `agent-infra-internal git-workflow snapshot --input {file}` to generate the reviewed diff fingerprint `F` and reviewed snapshot tree `T` together; write both into the report
+- Write `mode=worktree`, `baseline=R`, and `diffBase=D` to a temporary JSON file, then call `agent-infra-internal git-workflow snapshot --input {file}` to generate a reviewed diff fingerprint `F` for the complete committed range and a reviewed snapshot tree `T` for the current worktree; write R, D, F, and T into the report
 
+> After collecting those facts, read `.agents/rules/review-method.md`, use them as readiness evidence, and run Passes 2–5 for traceability, risk lenses, counterevidence, and classification; the report must record all five passes.
 > Detailed review criteria, severity rules, and reviewer expectations live in `reference/review-criteria.md`. Read `reference/review-criteria.md` before reviewing.
-> Test review gate: when `git diff` touches test files, read `.agents/rules/testing-discipline.md` first and check it item by item, especially "do not add negative assertions when a positive assertion already covers the behavior".
+
+Apply the shared five-pass protocol to code in this order:
+- Pass 1 reads the complete diff, untracked files, latest code artifact, approved plan/review-plan, task source, and raw test results.
+- Pass 2 maps acceptance/plan → implementation → verification and records changed lines, necessary callers/callees, state/data flow, and uncovered areas per file.
+- Pass 3 reviews overall design before per-file semantics, evaluates every shared registry trigger, and reads every matched reference in full. Test changes load `.agents/rules/testing-discipline.md` through the registry's `testing-discipline` lens; do not maintain a second trigger list.
+- Pass 4 checks guards, call constraints, test coverage, and narrower impact boundaries as counterevidence.
+- Pass 5 reconciles findings, manual-validation, advisories, evidence types, unverified assumptions, ledger state, and verdict.
+
+Complete the code implementation coverage in `reference/report-template.md`. Approval is forbidden when a matched reference is missing or unloaded, or when a risk gap remains unclassified.
 
 ### 5. Write the Review Report
 
@@ -85,10 +95,20 @@ Create `.agents/workspace/active/{task-id}/{review-artifact}`.
 
 Update task.md:
 - After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage code --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 code` 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
+- After all ledger writes, call `agent-infra-internal task-review {task-id} finalize-summary --stage code --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
 - Only when `canAdvance=true`, the verdict is Approved, and `T == R^{tree}`, write `last_reviewed_commit: {R}`. Clear an old value for an Approved snapshot with uncommitted differences; otherwise preserve the existing value and do not advance it
 - For an Approved exit, collect PR and required-checks facts as defined in `reference/output-templates.md`: route uncommitted/unpushed code to `commit`, no PR to `create-pr` (except no-PR flow), non-terminal checks to `watch-pr`, and route to `complete-task` only when `HEAD == last_reviewed_commit == PR head` with checks `passed|no-required`; never route by review round alone
-- After handling `last_reviewed_commit`, run `agent-infra-internal task-event {task-id} review-code.completed --agent {agent} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {n} --major {n} --minor {n} --manual-validation {n}`
+- After handling `last_reviewed_commit`, run `agent-infra-internal task-event {task-id} review-code.completed --agent {agent} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {unresolved-blockers} --major {unresolved-major} --minor {unresolved-minor} --manual-validation {n}`
 
 Always include the `Manual-validation: {n}` field in the done log, including when it is 0.
 `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.
@@ -130,7 +150,7 @@ manual-validation counts do not influence branch selection; they are displayed o
 
 > 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).
 
-Include all TUI command formats in the next-step output. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
+render the selected next-step commands through the shared helper. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
 
 ## Completion Checklist
 
@@ -138,7 +158,7 @@ Include all TUI command formats in the next-step output. If `.agents/.airc.json`
 - [ ] Created `{review-artifact}`
 - [ ] Updated task.md and appended the Activity Log entry
 - [ ] Chose exactly one verdict branch in the user output
-- [ ] Informed the user of the next step (must include all TUI command formats, including any custom TUIs; do not filter)
+- [ ] Rendered the selected next-step commands through the shared helper
 
 ## Notes
 

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

@@ -66,13 +66,23 @@ agent-infra-internal task-snapshot {task-id} --format text
 ### 4. 执行审查
 
 遵循 `.agents/workflows/feature-development.yaml`，并同时检查完整变更上下文：
-- 一次性记录 `R=$(git rev-parse HEAD)`；本轮报告、指纹和任务审查事实都复用该 R，禁止稍后重新读取 HEAD 代替
-- `git diff --binary "$R" -- <post-review-globs>` 覆盖已跟踪变更
+- 一次性记录审查提交 `R=$(git rev-parse HEAD)`；本轮报告、快照树和任务审查事实都复用该 R，禁止稍后重新读取 HEAD 代替
+- 调用 `agent-infra-internal platform-pr inspect {task-id}`：已绑定 PR 且返回 base SHA 时，令差异基线 `D=$(git merge-base "$R" "{base-sha}")`；无 PR 时仅在存在已跟踪或未跟踪工作区变化的前提下令 `D=$R`。无 PR 且工作区干净时无法可靠确定完整提交范围，必须停止并要求先绑定 PR，不得用空 diff 继续审查
+- `git diff --binary "$D" -- <post-review-globs>` 覆盖 `D` 到当前工作区的已提交与未提交跟踪变更
 - `git ls-files -o --exclude-standard -z -- <post-review-globs>` 覆盖未跟踪新文件
-- 把 `mode=worktree`、基线 `R` 写入临时 JSON，调用 `agent-infra-internal git-workflow snapshot --input {file}` 一次生成审查差异指纹 `F` 与审查快照树 `T`，并写入报告
+- 把 `mode=worktree`、`baseline=R`、`diffBase=D` 写入临时 JSON，调用 `agent-infra-internal git-workflow snapshot --input {file}` 一次生成覆盖完整提交范围的审查差异指纹 `F` 与当前工作区审查快照树 `T`；把 `R`、`D`、`F`、`T` 全部写入报告
 
+> 上述事实采集完成后，先读取 `.agents/rules/review-method.md`，以其作为 readiness 证据并按 Pass 2–5 完成追踪、风险镜头、反证和归类；报告必须记录全部五遍覆盖。
 > 详细审查标准、严重程度划分和 reviewer 关注点见 `reference/review-criteria.md`。执行此步骤前先读取 `reference/review-criteria.md`。
-> 测试审查硬门禁：当 `git diff` 触及测试文件时，必须先读取 `.agents/rules/testing-discipline.md` 并逐条核对（尤其"正向已覆盖时不应再加反向断言"）。
+
+代码阶段按以下顺序落实共享五遍协议：
+- Pass 1 读取完整 diff、未跟踪文件、最新 code artifact、已批准 plan/review-plan、任务来源和测试原始结果。
+- Pass 2 建立验收/方案—实现—验证映射，并逐文件记录 changed lines、必要调用方/被调用方、状态/数据流和未覆盖区域。
+- Pass 3 先检查整体设计，再检查逐文件语义；逐行判断共享风险镜头注册表，完整读取所有命中 reference。测试变更由注册表中的 `testing-discipline` 镜头加载 `.agents/rules/testing-discipline.md`，不得维护另一份触发清单。
+- Pass 4 检查保护条件、调用约束、测试覆盖和更窄影响范围等反证。
+- Pass 5 核对 finding、manual-validation、advisory、证据类型、未验证假设、账本和 verdict。
+
+报告必须填写 `reference/report-template.md` 中的代码实现专项覆盖；镜头命中但 reference 缺失/未加载，或风险缺口未分类时不得给出通过结论。
 
 ### 5. 编写审查报告
 
@@ -83,10 +93,20 @@ agent-infra-internal task-snapshot {task-id} --format text
 ### 6. 更新任务状态
 
 - 报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage code --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 code`。以 `stageStatus.canAdvance` 决定 verdict 和下一步，并以 `unresolvedFindingCounts` 填写 blocker/major/minor；仅 `canAdvance=true` 可用 Approved
+- 全部账本写入完成后只调用一次 `agent-infra-internal task-review {task-id} finalize-summary --stage code --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
 - 仅当 `canAdvance=true`、本轮结论为 Approved 且 `T == R^{tree}` 时写入 `last_reviewed_commit: {R}`；Approved 快照包含未提交差异时清除旧值。否则保留既有值，不得推进或清空
 - Approved 出口继续按 `reference/output-templates.md` 采集 PR 与 required-checks 事实：未提交/未推送走 `commit`，无 PR 走 `create-pr`（无 PR 流程除外），checks 未终态走 `watch-pr`，仅 `HEAD == last_reviewed_commit == PR head` 且 checks 为 `passed|no-required` 时走 `complete-task`；不得仅按审查轮次分流
-- 完成 `last_reviewed_commit` 处理后执行 `agent-infra-internal task-event {task-id} review-code.completed --agent {agent} --artifact {review-artifact} --verdict {approved|changes-requested|rejected} --blockers {n} --major {n} --minor {n} --manual-validation {n}`
+- 完成 `last_reviewed_commit` 处理后执行 `agent-infra-internal task-event {task-id} review-code.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: {n}` 字段，0 也保留。
 `manual-validation` 是 `ai task log` 中 review 行「人工校验点」（EN `Manual-validation`）计数的数据源；不要新增并行人工验证字段。
@@ -128,7 +148,7 @@ manual-validation 的数量不参与分支选择，只作为人工校验计数
 
 > 渲染最终输出前先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令的 `{task-ref}` 渲染为当前任务短号 `NN`（取值与回退见该文件），其他 `{task-id}` 占位（报告标题、路径）保持完整 TASK-id 形式；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
-向用户展示下一步时，必须包含所有 TUI 命令格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+向用户通过统一 helper 渲染已选场景的下一步命令。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 ## 完成检查清单
 
@@ -136,7 +156,7 @@ manual-validation 的数量不参与分支选择，只作为人工校验计数
 - [ ] 已创建 `{review-artifact}`
 - [ ] 已更新 task.md 并追加 Activity Log
 - [ ] 用户输出中只选择了一个审查结论分支
-- [ ] 告知了用户下一步（必须展示所有 TUI 的命令格式，含自定义 TUI，不要筛选）
+- [ ] 已通过统一 helper 渲染已选场景的下一步命令
 
 ## 注意事项