@fitlab-ai/agent-infra 0.9.0 → 0.9.2

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 渲染已选场景的下一步命令
 
 ## 注意事项
 

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

@@ -19,6 +19,9 @@
       "file_pattern": "review-code.md|review-code-r{N}.md",
       "required_sections": [
         "Review Summary",
+        "Review Coverage Declaration",
+        "Code Implementation Coverage",
+        "Traceability Matrix",
         "Findings",
         "Non-blocking Advisories",
         "Manual Validation Items",
@@ -33,10 +36,14 @@
         "^\\$ ",
         "^- \\*\\*Overall Verdict\\*\\*[:：]\\s*(?:通过|需要修改|拒绝|Approved|Changes Requested|Rejected)\\s*$",
         "^- \\*\\*Review Baseline Commit\\*\\*[:：]\\s*\\S",
+        "^- \\*\\*Reviewed Diff Base\\*\\*[:：]\\s*[0-9a-f]{40,64}\\s*$",
         "^- \\*\\*Reviewed Diff Fingerprint\\*\\*[:：]\\s*sha256:[0-9a-f]{64}\\s*$",
         "^- \\*\\*Reviewed Snapshot Tree\\*\\*[:：]\\s*[0-9a-f]{40,64}\\s*$"
       ]
     },
+    "review-summary": {
+      "stage": "code"
+    },
     "review-fact": {},
     "activity-log": {
       "expected_action_pattern": "(Review Code|Code Review) \\(Round \\d+\\)"

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

@@ -19,6 +19,9 @@
       "file_pattern": "review-code.md|review-code-r{N}.md",
       "required_sections": [
         "审查摘要",
+        "检视覆盖声明",
+        "代码实现专项覆盖",
+        "追踪矩阵",
         "问题清单",
         "非阻塞建议",
         "人工校验项",
@@ -33,10 +36,14 @@
         "^\\$ ",
         "^- \\*\\*总体结论\\*\\*[:：]\\s*(?:通过|需要修改|拒绝|Approved|Changes Requested|Rejected)\\s*$",
         "^- \\*\\*审查基线提交\\*\\*[:：]\\s*\\S",
+        "^- \\*\\*审查差异基线\\*\\*[:：]\\s*[0-9a-f]{40,64}\\s*$",
         "^- \\*\\*审查差异指纹\\*\\*[:：]\\s*sha256:[0-9a-f]{64}\\s*$",
         "^- \\*\\*审查快照树\\*\\*[:：]\\s*[0-9a-f]{40,64}\\s*$"
       ]
     },
+    "review-summary": {
+      "stage": "code"
+    },
     "review-fact": {},
     "activity-log": {
       "expected_action_pattern": "(Review Code|Code Review) \\(Round \\d+\\)"

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

@@ -0,0 +1,25 @@
+# Concurrency Risk Review
+
+## Scope
+
+Use when changes touch asynchronous coordination, shared state, locks, retries, idempotency, races, cancellation, or timeouts.
+
+## Review Questions
+
+- Are shared-state ownership, atomic boundaries, and visibility explicit?
+- Do retries, timeouts, cancellation, and duplicate delivery remain idempotent and resource-safe?
+- Can competing order or failure interleavings cause lost updates, duplicate side effects, or deadlocks?
+
+## Evidence Requirements
+
+Record key state transitions, event order, and synchronization boundaries. Support conclusions with deterministic concurrency tests, call chains, or data flows.
+
+## Common Counterexamples
+
+- Inferring concurrency safety from one successful sequential execution.
+- Checking only that a lock exists without its granularity, ordering, and release paths.
+- Replacing explainable evidence with one successful randomized stress run.
+
+## When Closure Is Not Possible
+
+Record reproducible races or leaks as findings, checks requiring a real scheduler or load environment as manual-validation, and uncovered interleavings as a gap.

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

@@ -0,0 +1,25 @@
+# 并发风险检视
+
+## 适用范围
+
+当变更触及异步协调、共享状态、锁、重试、幂等、竞态、取消或超时时使用。
+
+## 检视问题
+
+- 共享状态的所有权、原子边界和可见性是否明确。
+- 重试、超时、取消和重复交付是否保持幂等且不会泄漏资源。
+- 竞争顺序和失败交错是否会产生丢失更新、重复副作用或死锁。
+
+## 证据要求
+
+记录关键状态转换、事件顺序和同步边界；使用确定性并发测试、调用链或数据流支撑结论。
+
+## 常见反例
+
+- 单次顺序执行通过就推断并发安全。
+- 只检查加锁存在，不检查锁粒度、顺序和释放路径。
+- 用随机压力测试的单次成功替代可解释证据。
+
+## 无法闭环时
+
+可重现的竞态或资源泄漏形成 finding；需要真实调度器或负载环境的检查进入 manual-validation；未覆盖交错记录为 gap。

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

@@ -0,0 +1,27 @@
+# Cross-platform Risk Review
+
+## Scope
+
+Use when changes touch OS branches, path or case behavior, shells and commands, permissions, symlinks, newlines or encodings, signals and processes, or platform fallbacks.
+
+When the change also touches test files and must express real platform guards or test execution scope, read `.agents/rules/cross-platform-tests.md` in full. That second-level rule governs test scope only; this file governs implementation semantics. Do not load the second level when tests are unchanged.
+
+## Review Questions
+
+- Do paths, shells, permissions, and process behavior use the real semantics of each target platform?
+- Do platform fallbacks preserve consistent outcomes and distinguish unsupported behavior from runtime failure?
+- Do tests execute on genuinely supported platforms instead of simulating coverage with early returns?
+
+## Evidence Requirements
+
+Record affected platforms, implementation branches, and fallback paths. When test scope is involved, also record second-level rule readiness and `onPlatforms()` guards.
+
+## Common Counterexamples
+
+- Inferring equivalence across platforms from success on the development platform.
+- Simulating path or shell behavior with string concatenation.
+- Loading the test-guard rule unconditionally for formal completeness.
+
+## When Closure Is Not Possible
+
+Record reproducible platform defects as findings, checks that only a specific real platform can close as manual-validation, and actual platform risks left uncovered by missing, unloaded, or insufficient rules as a gap. A structural gate cannot replace semantic judgment.

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

@@ -0,0 +1,27 @@
+# 跨平台风险检视
+
+## 适用范围
+
+当变更触及 OS 分支、路径与大小写、shell/命令、权限、符号链接、换行/编码、信号/进程或平台回退时使用。
+
+若变更同时触及测试文件，且需要表达真实平台守卫或测试运行范围，继续完整读取 `.agents/rules/cross-platform-tests.md`。该二级规则只约束测试运行范围；本文件负责实现层的平台语义。没有测试变更时不加载二级规则。
+
+## 检视问题
+
+- 路径、shell、权限和进程行为是否使用目标平台真实语义。
+- 平台回退是否保留一致结果，并区分不支持与运行失败。
+- 测试是否在真实支持平台执行，而非用测试体内早返回伪装覆盖。
+
+## 证据要求
+
+记录受影响平台、实现分支和回退路径；涉及测试范围时同时记录二级规则加载证据和 `onPlatforms()` 守卫。
+
+## 常见反例
+
+- 用当前开发平台成功推断所有平台等价。
+- 以字符串拼接模拟路径或 shell 行为。
+- 为形式完整无条件加载测试守卫规则。
+
+## 无法闭环时
+
+可复现的平台缺陷形成 finding；只能在特定真实平台闭环的事项进入 manual-validation；规则缺失、未加载或未覆盖的实际平台风险记录为 gap，不得用结构 gate 替代语义判断。

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

@@ -0,0 +1,13 @@
+# Documentation Anti-patterns
+
+When reviewing new or changed documentation, require it to describe the current behavior after the change instead of using historical differences as a substitute for current facts.
+
+## Backward-looking Descriptions of Removed Functionality
+
+When functionality has been removed, current-behavior documentation should not keep saying that the functionality "no longer exists" or "was removed." Such wording keeps a deleted concept in the set of current knowledge that readers must understand.
+
+Terms such as `不再`, `no longer`, `已被移除`, `removed`, and `used to` can locate candidate text, but a match is not a finding by itself. Judge the documentation's purpose and change context:
+
+- Current reference documentation, rules, and usage instructions should directly describe supported behavior.
+- Migration guides, changelogs, and historical records may preserve necessary before-and-after differences when their historical or migration context is explicit.
+- Record a finding only when backward-looking wording preserves a deleted concept as current knowledge, and cite the exact file and line.

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

@@ -0,0 +1,13 @@
+# 文档反模式
+
+审查新增或修改的文档时，文档应描述变更后的当前行为，而不是用历史差异替代当前事实。
+
+## 已删除功能的反向描述
+
+当功能已经删除时，面向当前行为的文档不应继续写“该功能不再存在”或“该能力已被移除”。这类反向描述会让已删除概念继续成为读者必须理解的现行知识。
+
+`不再`、`no longer`、`已被移除`、`removed` 和 `used to` 等词可用于定位候选文本，但命中本身不是 finding。审查者必须结合文档用途和变更上下文判断：
+
+- 当前参考文档、规则和使用说明应直接描述现在支持的行为。
+- 迁移指南、变更日志和历史记录可以保留必要的前后差异，但应明确其历史或迁移语境。
+- 只有当反向措辞把已删除概念保留为现行知识时，才应登记 finding，并引用准确的文件和行号。

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

@@ -0,0 +1,25 @@
+# Migration and Compatibility Risk Review
+
+## Scope
+
+Use when changes touch persistent formats, schemas, configuration/frontmatter, compatibility reads, migrations, or rollback behavior.
+
+## Review Questions
+
+- Can old data or configuration be read safely, and is the post-write version boundary explicit?
+- Is migration repeatable, and can execution recover or continue after partial failure?
+- Does the rollback path match the compatibility window between old and new formats?
+
+## Evidence Requirements
+
+Record the transition from old input to new state, version decisions, and failure states. Prefer migration tests, fixtures, state transitions, or specification conflicts.
+
+## Common Counterexamples
+
+- Testing only fresh installation and ignoring existing state.
+- Assuming migration succeeds once while ignoring retries and partial writes.
+- Replacing data-semantic validation with format-existence checks.
+
+## When Closure Is Not Possible
+
+Record reproducible corruption or compatibility failures as findings, checks requiring real historical data as manual-validation, and missing samples or rollback evidence as a gap.

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

@@ -0,0 +1,25 @@
+# 迁移与兼容风险检视
+
+## 适用范围
+
+当变更触及持久化格式、schema、配置/frontmatter、兼容读取、迁移或回滚行为时使用。
+
+## 检视问题
+
+- 旧数据或旧配置能否被安全读取，写入后的版本边界是否明确。
+- 迁移是否可重复执行，部分失败后能否恢复或继续。
+- 回滚路径是否与新旧格式的兼容窗口一致。
+
+## 证据要求
+
+记录旧输入到新状态的转换、版本判定和失败状态；优先使用迁移测试、fixture、状态转换或规范冲突。
+
+## 常见反例
+
+- 只验证全新安装，不验证已有状态。
+- 假设迁移一次成功，忽略重试和部分写入。
+- 用格式存在性测试替代数据语义验证。
+
+## 无法闭环时
+
+可复现的数据损坏或兼容失败形成 finding；需要真实历史数据的验证进入 manual-validation；缺少样本或回滚证据时记录 gap。

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

@@ -17,11 +17,9 @@ Prohibitions:
 - never mix text from different branches
 - if `Blocker > 0`, never output an approval template
 - never count manual-validation findings as blockers / major issues / minor issues, and never use them to trigger Branch B/C/D
-- always include every TUI command format in the selected branch
+- generate `{next-step-commands}` for the selected branch through the shared helper
 - The count line shows 5 numbers. Manual-validation (`{e}`) does not affect selection. `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 Branches B/C/D, follow the revision commands with re-review commands: `/review-code {task-ref}`, `/{{project}}:review-code {task-ref}`, and `$review-code {task-ref}`.
-
 ### Branch A: Approved with No Findings
 
 Do not route by review round. Compare reviewed snapshot tree `T` with the tree of baseline `R`, then read `prFlow` / `pr_number`; when a PR exists, call `agent-infra-internal platform-checks inspect {task-id}`. Select exactly one mutually exclusive exit:
@@ -45,51 +43,51 @@ Reminder: manual-validation findings must be carried in the PR description as a
 
 #### Branch A1: Commit or Push
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill commit --task-ref {task-ref}`.
+
 ```text
 Next step - commit or push the code:
-  - Claude Code / OpenCode: /commit {task-ref}
-  - Gemini CLI: /{{project}}:commit {task-ref}
-  - Codex CLI: $commit {task-ref}
+{next-step-commands}
 ```
 
 #### Branch A2: Create a Pull Request
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill create-pr --task-ref {task-ref}`.
+
 ```text
 Next step - create a Pull Request:
-  - Claude Code / OpenCode: /create-pr {task-ref}
-  - Gemini CLI: /{{project}}:create-pr {task-ref}
-  - Codex CLI: $create-pr {task-ref}
+{next-step-commands}
 ```
 
 #### Branch A3: Watch Required Checks
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill watch-pr --task-ref {task-ref}`.
+
 ```text
 Next step - watch PR checks:
-  - Claude Code / OpenCode: /watch-pr {task-ref}
-  - Gemini CLI: /{{project}}:watch-pr {task-ref}
-  - Codex CLI: $watch-pr {task-ref}
+{next-step-commands}
 ```
 
 #### Branch A4: Complete and Archive
 
+Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}`.
+
 ```text
 Next step - complete and archive the task:
-  - Claude Code / OpenCode: /complete-task {task-ref}
-  - Gemini CLI: /{{project}}:complete-task {task-ref}
-  - Codex CLI: $complete-task {task-ref}
+{next-step-commands}
 ```
 
 ### Branch B: Changes Requested (Major / Minor)
 
+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} review completed. Verdict: changes requested.
 - Blockers: 0 | Major: {n} | Minor: {n} | Manual-validation: {e} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - fix the findings:
-  - 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 this final line:]
 Reminder: manual-validation findings must be carried in the PR description as a "manual verification required" checklist and should not trigger /code-task.
@@ -97,15 +95,15 @@ Reminder: manual-validation findings must be carried in the PR description as a
 
 ### Branch C: Changes Requested
 
+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} review completed. Verdict: changes requested.
 - Blockers: {n} | Major: {n} | Minor: {n} | Manual-validation: {e} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - fix the findings:
-  - 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 this final line:]
 Reminder: manual-validation findings must be carried in the PR description as a "manual verification required" checklist and should not trigger /code-task.
@@ -113,15 +111,15 @@ Reminder: manual-validation findings must be carried in the PR description as a
 
 ### Branch 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} review completed. Verdict: rejected, re-design the technical plan.
 - Blockers: {n} | Major: {n} | Minor: {n} | Manual-validation: {e} | Human-decision: {h}
 - Review report: .agents/workspace/active/{task-id}/{review-artifact}
 
 Next step - re-design 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}
 
 > Note: Rejected means the implementation direction needs to be reworked end-to-end, not patched locally. Core artifact lifecycle branch #7 refuses a direct `/code-task` and requires a fresh plan first.