@fitlab-ai/agent-infra 0.9.0 → 0.9.2

package/templates/.agents/rules/human-decision-context.zh-CN.md

@@ -4,32 +4,34 @@
 
 ## 自足性要求
 
-详情必须让维护者无需模型二次推理即可理解并裁决。每项必须明确说明背景、裁决目标、影响范围、风险、推荐方案与推荐理由，并至少提供两个可选方案；每个方案都必须同时列出收益和代价。
+详情必须让维护者不需要了解内部流程，也不需要再问模型，就能看懂并做选择。先用大白话说明为什么现在需要决定、具体要选什么、建议选哪个以及原因；再说明会影响什么、选错或暂不处理会怎样。
+
+每项至少提供两个有简短名称的方案，并分别写清好处和代价。第一次出现 stage、severity、evidence 等内部术语时，必须顺手解释它们的意思；ID 和 evidence 只用于后续查找和排查，不能代替问题说明。
 
 ## 规范结构
 
 ```markdown
 ### {AN-N|PL-N|CD-N|HD-N}：{标题} [needs-human-decision]
 
-- **背景**：{为何需要裁决；已知事实与约束}
-- **裁决目标**：{本次必须确定的唯一选择}
-- **影响范围**：{受影响的功能、文件、用户或后续先例}
-- **风险**：{错误选择、延期或不裁决的风险}
-- **推荐方案**：{方案 A/B/...}
-- **推荐理由**：{基于收益、代价和约束的理由}
+- **为什么现在要决定**：{用大白话说明已知情况、限制，以及为什么不能直接继续}
+- **要决定什么**：{本次只需要选定的一件事}
+- **建议选哪个**：{方案 A/B/...}
+- **为什么这样建议**：{结合好处、代价和现有限制说明原因}
+- **会影响什么**：{会受影响的功能、文件、用户或后续做法}
+- **如果选错或暂不处理**：{可能出现的问题}
 
 #### 方案 A：{名称}
 
-- **收益**：{选择该方案的收益}
-- **代价**：{选择该方案的成本与局限}
+- **好处**：{选择该方案能得到什么}
+- **代价**：{选择该方案要付出什么、有哪些局限}
 
 #### 方案 B：{名称}
 
-- **收益**：{选择该方案的收益}
-- **代价**：{选择该方案的成本与局限}
+- **好处**：{选择该方案能得到什么}
+- **代价**：{选择该方案要付出什么、有哪些局限}
 ```
 
-可增加方案 C 或补充证据，但不得省略上述字段或把多个方案压缩为无法分别比较的一行。标题 ID 必须与 task.md `## 审查分歧账本` 行一致，evidence 必须指向该标题的稳定锚点。
+可增加方案 C 或补充证据，但不得省略上述信息或把多个方案压缩为无法分别比较的一行。标题 ID 必须与 task.md `## 审查分歧账本` 行一致；evidence（用于定位原始说明的引用）必须指向该标题的稳定锚点。
 
 ## 裁决闭环
 

package/templates/.agents/rules/lifecycle-orchestration.en.md

@@ -0,0 +1,21 @@
+# Common Rule - Lifecycle Orchestration
+
+## Guarantee Boundary
+
+- The orchestrator only routes and delegates. Stage skills remain the single source of truth for behavior and artifacts.
+- Every stage and rework round uses a fresh executor. Every review uses a fresh reviewer; follow-up reuse is forbidden.
+- A reviewer may only write its review artifact and core-generated task metadata. Business-code, HEAD, or index changes invalidate the receipt.
+- An active run has one pending delegation. Missing, mismatched, forked, replayed, hook-less, or drifted evidence pauses the run.
+- The first release ends after one existing safely gated `commit`; it does not create a PR, monitor checks, or complete the task.
+
+## Recovery
+
+`orchestration.json` is the detailed state source. Re-entry reconciles first: completed runs return idempotently; recoverable pauses continue only after the blocker clears; unproven children, unsealed receipts, and baseline drift stay paused. Reviewer identities are never reused.
+
+## Model Policy
+
+Prefer a reviewer model different from the preceding executor. Same-model fallback must record requested model, actual model, and reason; an unrecorded fallback fails closed.
+
+## Stable Pause Conditions
+
+Human decisions, manual validation, handshake or step limits, permissions/network failures, worktree conflicts, unsupported client capability, and unknown hook schemas are persisted as pauses. The orchestrator must not ask mid-flow or degrade to same-context self-review.

package/templates/.agents/rules/lifecycle-orchestration.zh-CN.md

@@ -0,0 +1,21 @@
+# 通用规则 - 生命周期总控
+
+## 保证边界
+
+- 总控只路由和委派；阶段技能仍是业务规则与产物格式的单一事实源。
+- 每个阶段和每轮返工都创建 fresh executor；每轮审查创建 fresh reviewer，禁止 follow-up 复用。
+- reviewer 只能写当前审查产物和核心生成的任务元数据。业务代码、HEAD 或暂存区变化会使 receipt 失效。
+- active run 中只有一个 pending delegation。缺失、错配、fork、重放、hook 不可用或工作区漂移一律暂停。
+- 首版成功终点是一次通过既有安全门禁的 `commit`；不创建 PR、不监控 checks、不执行 `complete-task`。
+
+## 恢复语义
+
+`orchestration.json` 是详细状态源。重复入口先 reconcile：已完成 run 幂等返回；可恢复暂停在阻塞解除后继续；无法证明已停止的 child、未封存 receipt 或基线漂移继续保持暂停。旧 reviewer identity 永不复用。
+
+## 模型策略
+
+reviewer 优先选择与上一 executor 不同的模型。若客户端只能使用同模型，必须记录 requested model、actual model 和降级原因；缺少降级理由时失败关闭。
+
+## 稳定暂停条件
+
+人工裁决、人工验证、握手或总步骤上限、权限/网络失败、用户工作区冲突、客户端 capability 不支持及未知 hook schema 都持久化为暂停原因。总控不得中途询问或降级为同上下文自审。

package/templates/.agents/rules/next-step-output.en.md

@@ -20,6 +20,22 @@ This file defines four **independent** rules for a skill's "notify-user / Next s
 - **"Task info" / "Task status" structured field lines** → show full id and short id together: `- Task ID: {task-id} (short id {task-ref})`.
 - **Report titles** (`Task {task-id} ... completed`) and **artifact paths** (`.agents/workspace/active/{task-id}/...`) → keep the full `{task-id}` (physical path and archive key, must not change).
 
+## Unified Client Command Rendering
+
+Next-step client commands must come from the shared helper; skills and output templates must not assemble client command tables themselves:
+
+```bash
+agent-infra-internal agent-client next-steps \
+  --skill {next-skill-name} \
+  [--task-ref {task-ref}]
+```
+
+- Pass the next skill name for the already-selected scenario. Include `--task-ref` only when that command needs a task reference.
+- The helper lists only built-in clients enabled in `.agents/.airc.json` `agentClients`, followed by valid `customTUIs` in configuration order.
+- Insert non-empty stdout verbatim at `{next-step-commands}` below the current "Next steps" heading. When stdout is empty, omit the client command block while still rendering reminders, warnings, and `Completed at`.
+- If the helper writes stderr or exits non-zero, use the current skill's error path and stop; never fall back to a hard-coded client table.
+- A complex skill selects one scenario first and invokes the helper once for that scenario; it must not pre-render every branch.
+
 ## Obtaining the short id (`{task-ref}`)
 
 The single source of truth for short ids is the registry `.agents/workspace/active/.short-ids.json` (via `task-short-id.js`). **Never** read the `short_id` field from task.md frontmatter (that field is not authoritative).

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -20,6 +20,22 @@
 - **「任务信息」/「任务状态」结构化字段行** → 完整 ID 与短号同显：`- 任务 ID：{task-id}（短号 {task-ref}）`。
 - **报告标题**（`任务 {task-id} ... 完成`）与**产出文件路径**（`.agents/workspace/active/{task-id}/...`）→ 保持完整 `{task-id}`（物理路径与归档键，不可改）。
 
+## 统一客户端命令渲染
+
+下一步客户端命令必须由统一 helper 生成，skill 和输出模板不得自行拼接客户端命令表：
+
+```bash
+agent-infra-internal agent-client next-steps \
+  --skill {next-skill-name} \
+  [--task-ref {task-ref}]
+```
+
+- 静态传入当前已选场景的下一 skill 名；只有命令需要任务引用时才传 `--task-ref`。
+- helper 只展示 `.agents/.airc.json` 中 `agentClients` 已启用的内建客户端，并在其后按配置顺序追加合法的 `customTUIs`。
+- 将非空 stdout 原样放入当前“下一步”标题后的 `{next-step-commands}`；stdout 为空时省略整个客户端命令块，但继续输出提醒、告警和 `Completed at`。
+- helper 写 stderr 或返回非零时，按当前 skill 的错误路径报告并停止；禁止回退到硬编码客户端表。
+- 复杂 skill 先选定唯一场景，再只为该场景调用一次 helper，不得提前渲染所有分支。
+
 ## 取短号（`{task-ref}`）
 
 短号唯一真源是注册表 `.agents/workspace/active/.short-ids.json`（经 `task-short-id.js`）。**禁止**读取 task.md frontmatter 的 `short_id` 字段（该字段不可信）。

package/templates/.agents/rules/no-mid-flow-questions.en.md

@@ -78,6 +78,8 @@ A mandatory human review checkpoint means:
 
 If a key decision needs human judgment during execution, follow the rule above and register the detail identity through the structured `decision-next-id` / `decision-upsert` commands for the user to address at the review checkpoint; ordinary open questions still go to `## Open Questions` / `未决问题`.
 
+The `run-task` orchestrator may continue after a child skill artifact only when core mechanical state permits it; this does not bypass human decisions. When core reports a human decision, manual validation, or another stable pause condition, the orchestrator must stop without asking mid-flow or approving it itself.
+
 ## Anchor Location
 
 This rule's sole global anchor lives in the project-level AGENTS.md "AI Behavior Principles" preamble, which every AI tool loads. Individual SKILL.md files no longer reference this rule, so no per-skill duplicate bullet needs to be maintained.

package/templates/.agents/rules/no-mid-flow-questions.zh-CN.md

@@ -78,6 +78,8 @@
 
 如果在执行过程中发现需要用户裁定的关键决策，按上文「关键设计决策标记与落账」处理：通过 `decision-next-id` / `decision-upsert` 结构化命令登记详情块与账本身份，由用户在审查检查点统一回应；普通未决问题仍写 `## 未决问题` / `Open Questions`。
 
+`run-task` 总控可以在子技能产出后依据核心机械状态继续到下一阶段；这不构成绕过人工裁决。只要核心返回人工裁决、人工验证或其他稳定暂停条件，总控必须停止，不能向用户中途提问，也不能自行批准。
+
 ## 锚点位置
 
 本规则的唯一全局锚点在项目级 AGENTS.md 的「AI 行为准则」preamble，所有 AI 工具加载 AGENTS.md 时即可见。各 SKILL.md 不再单独引用本规则，避免在每个 SKILL 顶部维护重复 bullet。

package/templates/.agents/rules/release-commands.en.md

@@ -1,5 +1,5 @@
 # Release Commands
 
-This code platform does not provide built-in release commands.
+This code platform does not provide a release-note adapter.
 
-Remote release automation is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and scripts. Continue using local release artifacts or your platform-specific release process.
+Use `agent-infra-internal platform-release-notes context` to receive a structured `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op. Do not probe another platform client. Publishing remains a no-op until an adapter is provided.

package/templates/.agents/rules/release-commands.github.en.md

@@ -1,52 +1,28 @@
 # Release Platform Commands
 
-Read this file before loading release history, querying merged PRs, or publishing the Release notes.
+Release-note platform operations use a typed internal intent. Callers consume structured JSON and do not interpret platform commands, raw fields, identity email rules, or authentication errors.
 
-## Query Releases
+## Collect Release-note Context
 
 ```bash
-gh release list --limit {limit} --json tagName,isDraft,isPrerelease
-gh release view "{tag}" --json body,url
+agent-infra-internal platform-release-notes context \
+  --from-tag "v{prev-version}" \
+  --to-tag "v{version}" \
+  --branch "{branch}" \
+  --history-limit 3
 ```
 
-## Query Merged PRs
+The result contains `history`, `pullRequests`, `closingIssues`, and commit `authors` with normalized `login` / `resolution` values. `status: no-op` with error code `PLATFORM_RELEASE_NOTES_UNSUPPORTED` means the current platform does not support remote release-note operations.
 
-```bash
-gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels
-```
-
-When needed, read the linked Issue:
-
-```bash
-gh issue view {issue-number} --json number,title,labels,url
-```
-
-## Contributor Mapping Helpers
-
-Merged PR queries used for release notes should include authors when contributors are needed:
-
-```bash
-gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels,author
-```
-
-Linked Issue queries used for reporter attribution should include the author:
-
-```bash
-gh issue view {issue-number} --json number,title,labels,url,author
-```
-
-Map GitHub no-reply emails with this rule: if `Name <email>` contains an email matching `(\d+\+)?(\S+?)@users\.noreply\.github\.com`, use the second capture group lowercased as the login. This covers both `{id}+{login}@users.noreply.github.com` and `{login}@users.noreply.github.com`.
-
-## Publish the Release Notes
+## Publish Release Notes
 
-The GitHub Release for `v{version}` is created and published automatically by the release workflow so Homebrew bottles have a stable upload target. This command writes the curated notes onto that existing Release, falling back to creating it if it does not exist yet.
+Call this only after user confirmation:
 
 ```bash
-if gh release view "v{version}" >/dev/null 2>&1; then
-  gh release edit "v{version}" --notes-file "{notes-file}"
-else
-  gh release create "v{version}" --title "v{version}" --notes-file "{notes-file}"
-fi
+agent-infra-internal platform-release-notes publish \
+  --tag "v{version}" \
+  --title "v{version}" \
+  --notes-file "{notes-file}"
 ```
 
-If commands fail, stop or escalate according to the calling skill.
+The command updates an existing Release or creates it when missing; `--dry-run` returns only the planned operation. Exit code `0` means success, `1` means a stable failure, and `2` means a network or platform block.

package/templates/.agents/rules/release-commands.github.zh-CN.md

@@ -1,52 +1,28 @@
 # Release 平台命令
 
-在读取历史 release、查询已合并 PR，或发布 Release notes 前先读取本文件。
+发布说明平台操作统一使用 typed internal intent。调用方只解释结构化 JSON，不解析平台命令、原始字段、身份邮箱规则或认证错误。
 
-## Release 查询
+## 收集发布说明上下文
 
 ```bash
-gh release list --limit {limit} --json tagName,isDraft,isPrerelease
-gh release view "{tag}" --json body,url
+agent-infra-internal platform-release-notes context \
+  --from-tag "v{prev-version}" \
+  --to-tag "v{version}" \
+  --branch "{branch}" \
+  --history-limit 3
 ```
 
-## 已合并 PR 查询
-
-```bash
-gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels
-```
-
-必要时读取关联 Issue：
-
-```bash
-gh issue view {issue-number} --json number,title,labels,url
-```
-
-## Contributor 映射辅助规则
-
-release notes 需要 contributors 时，已合并 PR 查询应包含 author：
-
-```bash
-gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels,author
-```
-
-关联 Issue 用于 reporter 归因时，查询应包含 author：
-
-```bash
-gh issue view {issue-number} --json number,title,labels,url,author
-```
-
-GitHub no-reply 邮箱映射规则：如果 `Name <email>` 中的 email 匹配 `(\d+\+)?(\S+?)@users\.noreply\.github\.com`，使用第二个捕获组的小写形式作为 login。该规则同时覆盖 `{id}+{login}@users.noreply.github.com` 和 `{login}@users.noreply.github.com`。
+结果包含 `history`、`pullRequests`、`closingIssues` 和带规范化 `login` / `resolution` 的 commit `authors`。`status: no-op` 且错误码为 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` 表示当前平台不支持远端发布说明能力。
 
 ## 发布 Release notes
 
-`v{version}` 的 GitHub Release 由 release 工作流自动创建并发布，为 Homebrew bottle 提供稳定的上传落点。本命令把精修后的 notes 写到这个已存在的 Release 上；若 Release 尚不存在则兜底创建。
+用户确认后调用：
 
 ```bash
-if gh release view "v{version}" >/dev/null 2>&1; then
-  gh release edit "v{version}" --notes-file "{notes-file}"
-else
-  gh release create "v{version}" --title "v{version}" --notes-file "{notes-file}"
-fi
+agent-infra-internal platform-release-notes publish \
+  --tag "v{version}" \
+  --title "v{version}" \
+  --notes-file "{notes-file}"
 ```
 
-失败时按调用方规则停止或提示人工介入。
+命令会更新已存在的 Release，缺失时创建；`--dry-run` 只返回 planned operation。退出码为 `0` 时成功，`1` 表示稳定失败，`2` 表示网络或平台阻塞。

package/templates/.agents/rules/release-commands.zh-CN.md

@@ -1,5 +1,5 @@
 # Release 命令
 
-当前代码平台未内置发布命令支持。
+当前代码平台未提供发布说明 adapter。
 
-自定义平台会跳过远端发布自动化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和脚本。请继续使用本地发布产物或你的平台专属发布流程。
+调用 `agent-infra-internal platform-release-notes context` 会返回结构化的 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op，不得探测其他平台 client。在提供 adapter 前，发布操作同样保持 no-op。

package/templates/.agents/rules/review-handshake.en.md

@@ -84,15 +84,16 @@ When an executor judges an item to be a key design decision that needs human rul
 - `evidence` points to the stable anchor `<artifact>#HD-N` (e.g. `plan-r2.md#HD-1`), not a drift-prone line number.
 - A human records the ruling with `ai decide <task-ref> <ordinal|ledger-id> <decision>`; the command flips the target row to `human-decided` and points `evidence` to an independent `HDR-N` ruling record.
 
-> Viewing, deciding, and typed verification share the `lib/task/ledger.ts` domain semantics.
+> Viewing, deciding, and typed verification share the `lib/task/ledger.ts` domain semantics; no second parser is maintained.
 
 ## post-review commit gate (code stage only)
 
-- `review-code` captures the review baseline `R` (diff base), full-worktree diff fingerprint `F`, and normalized snapshot tree `T`. An Approved clean snapshot may set `B=R`; an Approved snapshot with uncommitted changes clears or omits `B`.
+- `review-code` captures the reviewed commit `R` (this round's HEAD) and an independent diff base `D` exactly once. `F` covers the complete difference from D to the current worktree, while normalized snapshot tree `T` represents the current worktree. An Approved snapshot with `T == R^{tree}` may set `B=R`; an Approved snapshot with uncommitted changes clears or omits `B`.
 - `commit` reads only the highest-round Approved `review-code` artifact. Before committing it requires `pre_head == R`, complete worktree tree `W == T`, and normalized staged tree `S == T`; any mismatch blocks before `git commit` and reports added, missing, and different paths for both comparisons.
 - After a successful commit it sets `B=last_reviewed_commit=<new_head>`; B means only a reviewed snapshot anchored to a Git commit.
 - The `complete-task` `post-review-commit` gate uses only B. When B is absent, malformed, or missing as a Git object, it reports `reviewed snapshot was not anchored` and never falls back to R.
-- If new commits touch code / rule paths after B, the gate blocks and requires a fresh `review-code`.
+- If new commits touch code / rule paths after B, the gate blocks and requires a fresh `review-code`. Automatic exceptions are limited to: (1) a bound platform change request (PR/MR) is merged and its platform adapter supplies an authoritative snapshot plus remote Git evidence refs; the gate fetches the reviewed head and target branch into an isolated temporary repository and proves B is the original change-request head, its merge commit is in authoritative target history, its reviewed changes exactly match the normalized patch of a single-parent squash commit, and its protected paths have no later commits; or (2) no valid change request, exactly one protected-path commit after B, that commit is a single-parent local rewrite in HEAD history, it has the same full tree or protected content as B, and no protected-path commits follow it. An unsupported adapter capability, missing required platform / Git evidence, or Git credentials that cannot read those remote refs fails closed.
+- Required checks remain a pre-merge responsibility of branch protection / rulesets and the `review-code` / `watch-pr` routes. The post-review-commit gate still applies the applicable strict, PR-squash, or local-rewrite equivalence independently.
 - **Exemption**: append a ledger row `| PRC-1 | post-review-commit | - | - | human-decided | <ruling note> |` recording that a human explicitly allowed those commits without re-review.
 
 ## Gate behavior cheat sheet

package/templates/.agents/rules/review-handshake.zh-CN.md

@@ -84,15 +84,16 @@
 - `evidence` 指向稳定锚点 `<artifact>#HD-N`（如 `plan-r2.md#HD-1`），不依赖易漂移的行号。
 - 人工使用 `ai decide <task-ref> <序号|账本ID> <裁决内容>` 记录裁定；命令把目标行翻为 `human-decided`，并让 `evidence` 指向独立 `HDR-N` 裁定记录。
 
-> 查看、裁决与 typed verification 共用 `lib/task/ledger.ts` 的领域语义。
+> 查看、裁决与 typed verification 共用 `lib/task/ledger.ts` 的领域语义，不维护第二 parser。
 
 ## post-review commit 门禁（仅 code 阶段）
 
-- `review-code` 一次性捕获审查基线 `R`（diff base）、完整工作区差异指纹 `F` 与规范化快照树 `T`；Approved 且快照干净时可令 `B=R`，Approved 且含未提交差异时清除/不写 `B`。
+- `review-code` 一次性捕获审查提交 `R`（本轮 HEAD）与独立差异基线 `D`；`F` 覆盖 `D` 到当前工作区的完整差异，规范化快照树 `T` 表示当前工作区。Approved 且 `T == R^{tree}` 时可令 `B=R`，Approved 且含未提交差异时清除/不写 `B`。
 - `commit` 只读取最高轮 Approved `review-code` 产物；提交前比较 `pre_head == R`、完整工作区树 `W == T`、规范化暂存树 `S == T`，任一失配都在 `git commit` 前阻断并报告两组 added/missing/different 路径。
 - 成功提交后令 `B=last_reviewed_commit=<new_head>`；`B` 只表示已经落到 Git commit 的审查锚点。
 - `complete-task` 的 `post-review-commit` gate 只使用 B；B 缺失、畸形或对象不存在时报告 `reviewed snapshot was not anchored`，不得回退 R。
-- 若 B 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。
+- 若 B 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。自动例外仅限两类：(1) 绑定的平台变更请求（PR/MR）已合并，且平台适配器提供权威快照与远端 Git 证据引用；gate 在隔离的临时仓库中抓取受审查 head 与目标分支，证明 B 是原变更请求 head、merge commit 位于权威目标分支历史中、受审查变更与单父 squash commit 的规范化补丁完全一致，并且 merge 后受保护路径没有新提交；(2) 无有效变更请求，B 后恰有一个受保护路径提交，该提交是本地 HEAD 历史中的单父重写，且它与 B 的完整 tree 相同或受保护内容相同，重写后也没有受保护路径提交。适配器不支持该能力，缺少所需平台 / Git 证据，或当前 Git 凭据不能读取这些远端 refs 时 fail closed。
+- required checks 由合并前的分支保护 / ruleset 与 `review-code` / `watch-pr` 路由负责。post-review-commit 仍独立执行适用的严格 / PR squash / 本地重写等价判定。
 - **豁免**：在账本追加一行 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`，记录人工明确允许该批提交免复审。
 
 ## gate 行为速查

package/templates/.agents/rules/review-method.en.md

@@ -0,0 +1,113 @@
+# Shared Review Method
+
+This rule defines the lightweight review protocol shared by the `analysis`, `plan`,
+and `code` stages. Stage-specific checks remain in each skill's
+`reference/review-criteria.md`; finding state, human decisions, and ledger writes
+remain governed by [review-handshake.md](review-handshake.md); risk lenses only route
+an observed risk to references that must then be loaded.
+
+## Responsibility Boundary
+
+- This rule defines review order, evidence shape, and completion conditions without duplicating stage checklists.
+- Observable evidence triggers risk lenses; every matched reference must be read and recorded in the report.
+- Automation supplies facts; the reviewer judges completeness, impact, severity, confidence, and counterevidence.
+- Report structure makes review claims traceable; it does not automatically prove that semantic judgments are correct.
+
+## Readiness
+
+Before forming candidate findings, confirm that:
+
+1. The task, input artifact, upstream sources, and review scope are resolved and readable.
+2. The state snapshot, diff, or other factual evidence required by the skill has been captured.
+3. The reviewed artifact, baseline, and context boundary can be identified accurately in the report.
+
+If any prerequisite is missing, an Approved verdict is forbidden; follow the owning
+skill's blocked or failure path.
+
+## Multi-pass Review Protocol
+
+Run these five passes in order. Record each pass's scope, evidence, result, and
+gaps/assumptions in the report coverage table.
+
+1. **Pass 1 — Raw evidence**: read source requests, upstream artifacts, changes, and tests before executor summaries can anchor the review; form independent candidate issues.
+2. **Pass 2 — Traceability and boundaries**: map source → requirement → plan → implementation → test, looking for omissions, broken links, and unexpected scope.
+3. **Pass 3 — Risk lenses**: evaluate every registry trigger against the complete context, load every matched reference, and record trigger evidence and results.
+4. **Pass 4 — Counterevidence**: seek evidence that disproves or downgrades each candidate finding and counterexamples that could invalidate an approval.
+5. **Pass 5 — Classification and convergence**: classify issues as findings, manual-validation, or advisories; reconcile evidence contracts, ledger intents, unverified assumptions, and the verdict.
+
+## Risk Lens Registry
+
+Registry rows use stable fields: `lens_id` identifies the lens, `stages` limits its
+scope, `observable_trigger` states observable evidence, `required_reference` is
+mandatory when matched, and `report_evidence` defines the audit trail.
+
+| lens_id | stages | observable_trigger | required_reference | report_evidence |
+|---------|--------|--------------------|--------------------|-----------------|
+| documentation-antipatterns | code | The complete change context touches Markdown, rules, skills, CLI help, or user documentation that describes current behavior | `.agents/skills/review-code/reference/documentation-antipatterns.md` | Record triggering files, `loaded=yes`, and the lens result |
+| testing-discipline | code | The complete change context touches tests, fixtures, snapshots, or test helpers | `.agents/rules/testing-discipline.md` | Record triggering files, `loaded=yes`, and the test-discipline result |
+| security-risks | code | Authentication, authorization, untrusted input, sensitive data, credentials, cryptography, dependencies, or system boundaries change | `.agents/skills/review-code/reference/security-risks.md` | Record the changed security boundary, `loaded=yes`, and the lens result |
+| migration-risks | code | Persistent formats, schemas, configuration/frontmatter, compatibility reads, migrations, or rollback behavior change | `.agents/skills/review-code/reference/migration-risks.md` | Record compatibility or migration evidence, `loaded=yes`, and the lens result |
+| concurrency-risks | code | Async coordination, shared state, locks, retries, idempotency, races, cancellation, or timeouts change | `.agents/skills/review-code/reference/concurrency-risks.md` | Record the concurrency path, `loaded=yes`, and the lens result |
+| cross-platform-risks | code | OS branches, paths, shells, permissions, symlinks, newlines, signals, or cross-platform behavior change | `.agents/skills/review-code/reference/cross-platform-risks.md` | Record platform evidence, `loaded=yes`, and the lens result |
+
+Unmatched lenses still require reproducible non-trigger evidence. `loaded` accepts
+only `yes`, `no`, or `not-applicable`; a matched but unloaded lens forbids approval.
+
+## Automation and Semantic Judgment
+
+| Source | Facts it can support | Semantic judgment it cannot replace |
+|--------|----------------------|-------------------------------------|
+| snapshot, diff, link, test, artifact gate | files, scope, command results, reference existence, section existence | requirement completeness, design soundness, implementation correctness |
+| traceability matrix | explicit mappings and visible gaps | mapping sufficiency, gap impact, priority |
+| risk-lens record | trigger evidence, load status, lens result entry point | acceptable risk, finding severity, confidence |
+
+When automated facts and semantic conclusions diverge, record each separately.
+Never present a passing structural gate as proof of semantic completeness.
+
+## Context Coverage and Traceability Contract
+
+Reports must contain both coverage tables:
+
+| pass_id | scope | evidence | result | gaps_or_assumptions |
+|---------|-------|----------|--------|---------------------|
+| pass-1..5 | scope actually reviewed in this pass | locatable artifact, file, command, or line | finding or conclusion | uncovered item, gap, or assumption |
+
+| lens_id | trigger_evidence | loaded | result |
+|---------|------------------|--------|--------|
+| registry token | reproducible trigger or non-trigger evidence | yes / no / not-applicable | lens conclusion |
+
+Reports must also contain the shared traceability matrix:
+
+| source_id | upstream | reviewed_target | verification | status_or_gap |
+|-----------|----------|-----------------|--------------|---------------|
+| stable source identifier | upstream requirement, decision, or step | object reviewed at this stage | automated or human evidence | covered / gap and impact |
+
+Analysis traces sources to requirements, acceptance, impact, and risk. Plan traces
+approved requirements to decisions, implementation steps, and test strategy. Code
+traces requirements and plan steps to the diff and automated tests or human checks.
+
+## Finding Evidence Contract
+
+Every blocker or major finding must include:
+
+1. **Scenario**: preconditions and the path that triggers the problem.
+2. **Impact**: concrete consequences for correctness, security, delivery, or acceptance.
+3. **Evidence**: reproducible artifact, `file:line`, command, and raw result.
+4. **Confidence**: stable token `high`, `medium`, or `low`.
+5. **Unverified assumptions**: claims not directly proven that would change the conclusion if disproved; explicitly state none when empty.
+6. **Fix direction**: the smallest actionable repair goal without redesigning outside the executor's authority.
+
+Minor findings stay lightweight but still need a specific location and actionable
+advice. The finding ledger's `evidence` continues to point to a stable report anchor;
+no ledger fields are added. Handle manual-validation, advisories, and
+`needs-human-decision` through the review handshake and stage rules.
+
+## Completion
+
+A final verdict is allowed only when:
+
+- All five passes record scope, evidence, result, and gaps/assumptions.
+- Every risk trigger has a decision, and every matched lens was loaded and recorded.
+- The traceability matrix covers the stage responsibility, with gaps classified as a finding, manual-validation, advisory, or explicit assumption.
+- Every blocker/major satisfies the evidence contract and every candidate finding received a counterevidence pass.
+- Ledger intents, manual checks, pending decisions, unverified assumptions, and finding counts agree.

package/templates/.agents/rules/review-method.zh-CN.md

@@ -0,0 +1,98 @@
+# 通用检视方法
+
+本规则定义 `analysis`、`plan` 和 `code` 三个审查阶段共用的轻量检视协议。阶段专属检查项留在各 skill 的 `reference/review-criteria.md`；finding 状态机、人工裁决和账本写入继续以 [review-handshake.md](review-handshake.md) 为准；风险镜头只承载命中某类风险后必须加载的专项 reference。
+
+## 职责边界
+
+- 本规则规定审查顺序、证据形状和完成条件，不复制阶段 checklist。
+- 风险镜头由可观察证据触发；命中后必须读取全部对应 reference，并在报告留证。
+- 自动化检查提供事实，reviewer 负责完整性、影响、严重度、置信度和反证等语义判断。
+- 报告结构证明审查声明可追溯，不等于自动证明语义判断正确。
+
+## Readiness
+
+形成候选 finding 前必须确认：
+
+1. 任务、输入 artifact、上游来源和审查范围已解析且可读。
+2. skill 要求的状态快照、差异或其他事实证据已捕获。
+3. 本轮实际审查的 artifact、基线和上下文边界可在报告中准确标识。
+
+任一前置项缺失时，不得给出通过结论；按所属 skill 的阻塞或失败路径处理。
+
+## 多遍检视协议
+
+按顺序执行以下五遍；每遍都在报告的检视覆盖表中记录范围、证据、结果与缺口/假设。
+
+1. **Pass 1 — 原始证据**：先读任务来源、上游 artifact、变更和测试等原始证据，独立形成候选问题，避免被执行方摘要锚定。
+2. **Pass 2 — 追踪与边界**：建立来源—需求—方案—实现—测试追踪，识别遗漏、断链和意外范围扩张。
+3. **Pass 3 — 风险镜头**：依据完整上下文逐项判断注册表触发器，加载所有命中的专项 reference，并记录命中证据与结果。
+4. **Pass 4 — 反证**：主动寻找能推翻或降级每个候选 finding 的证据，并检查放行结论可能失败的反例。
+5. **Pass 5 — 归类与收敛**：将问题归为 finding、manual-validation 或 advisory，核对证据契约、账本意图、未验证假设和 verdict。
+
+## 风险镜头注册表
+
+注册行使用稳定字段：`lens_id` 标识镜头，`stages` 限定阶段，`observable_trigger` 给出可观察触发条件，`required_reference` 是命中后必读路径，`report_evidence` 规定报告留证。
+
+| lens_id | stages | observable_trigger | required_reference | report_evidence |
+|---------|--------|--------------------|--------------------|-----------------|
+| documentation-antipatterns | code | 完整变更上下文触及描述当前行为的 Markdown、规则、skill、CLI 帮助或用户文档 | `.agents/skills/review-code/reference/documentation-antipatterns.md` | 记录触发文件、`loaded=yes` 与检视结果 |
+| testing-discipline | code | 完整变更上下文触及测试、fixture、snapshot 或测试 helper | `.agents/rules/testing-discipline.md` | 记录触发文件、`loaded=yes` 与测试纪律结论 |
+| security-risks | code | 认证授权、非可信输入、敏感数据、凭据、加密、依赖或系统边界发生变化 | `.agents/skills/review-code/reference/security-risks.md` | 记录安全边界变化、`loaded=yes` 与检视结果 |
+| migration-risks | code | 持久化格式、schema、配置/frontmatter、兼容读取或迁移/回滚发生变化 | `.agents/skills/review-code/reference/migration-risks.md` | 记录兼容或迁移触发证据、`loaded=yes` 与检视结果 |
+| concurrency-risks | code | 异步协调、共享状态、锁、重试、幂等、竞态、取消或超时发生变化 | `.agents/skills/review-code/reference/concurrency-risks.md` | 记录并发触发路径、`loaded=yes` 与检视结果 |
+| cross-platform-risks | code | OS 分支、路径、shell、权限、符号链接、换行、信号或跨平台行为发生变化 | `.agents/skills/review-code/reference/cross-platform-risks.md` | 记录平台触发证据、`loaded=yes` 与检视结果 |
+
+未命中镜头也必须记录可复核的未命中证据。`loaded` 只使用 `yes`、`no`、`not-applicable`；命中但未加载时不得给出通过结论。
+
+## 自动化与语义判断
+
+| 来源 | 可支持的事实 | 不可替代的语义判断 |
+|------|--------------|--------------------|
+| snapshot、diff、link、test、artifact gate | 文件、范围、命令结果、引用存在、章节存在 | 需求是否完整、设计是否合理、实现是否正确 |
+| 追踪矩阵 | 显式映射及可见缺口 | 映射是否充分、缺口影响和优先级 |
+| 风险镜头记录 | 触发证据、加载状态、专项结果入口 | 风险是否可接受、finding 严重度与置信度 |
+
+自动化结果与语义结论冲突时，报告必须分别记录事实与推理，不得把结构 gate 的通过写成语义完整性的证明。
+
+## 上下文覆盖与追踪契约
+
+报告必须包含两张覆盖表：
+
+| pass_id | scope | evidence | result | gaps_or_assumptions |
+|---------|-------|----------|--------|---------------------|
+| pass-1..5 | 本遍实际覆盖范围 | 可定位的 artifact、文件、命令或行号 | 发现或结论 | 未覆盖项、缺口或假设 |
+
+| lens_id | trigger_evidence | loaded | result |
+|---------|------------------|--------|--------|
+| 注册表 token | 命中或未命中的可复核证据 | yes / no / not-applicable | 专项检视结论 |
+
+并包含统一追踪矩阵：
+
+| source_id | upstream | reviewed_target | verification | status_or_gap |
+|-----------|----------|-----------------|--------------|---------------|
+| 稳定来源标识 | 上游需求、决策或步骤 | 本阶段被审对象 | 自动化或人工证据 | covered / gap 及影响 |
+
+analysis 阶段追踪来源到需求、验收、影响和风险；plan 阶段追踪已批准需求到设计决策、步骤和测试策略；code 阶段追踪需求/方案到 diff 与自动化测试或人工校验。
+
+## Finding 证据契约
+
+每个 blocker 或 major finding 必须包含：
+
+1. **场景**：触发问题的前置条件和路径。
+2. **影响**：对正确性、安全、交付或验收的具体后果。
+3. **证据**：可复现的 artifact、`file:line`、命令和原始结果。
+4. **置信度**：稳定 token `high`、`medium` 或 `low`。
+5. **未验证假设**：尚未直接证明、若被推翻会改变结论的假设；没有则明确写无。
+6. **修复方向**：可执行的最小修复目标，不替执行方越权重设计。
+
+minor 保持轻量，但仍须提供具体位置和可执行建议。finding ledger 的 `evidence` 继续指向报告中的稳定锚点，不新增账本字段。manual-validation、advisory 和 `needs-human-decision` 按 review handshake 与阶段规则处理。
+
+## Completion
+
+只有同时满足以下条件才可形成最终 verdict：
+
+- 五遍检视均已记录范围、证据、结果和缺口/假设。
+- 所有风险触发器均有命中判断，命中镜头均已加载并留证。
+- 追踪矩阵覆盖本阶段职责，缺口已进入 finding、manual-validation、advisory 或明确假设。
+- 所有 blocker/major 满足统一证据契约，候选 finding 已完成反证检视。
+- 账本意图、人工校验、待裁决项、未验证假设与问题计数一致。

package/templates/.agents/rules/testing-discipline.en.md

@@ -41,6 +41,24 @@ This mirrors "Goal-Driven Execution" in AGENTS.md: define a verifiable success c
 
 ## Project-specific test policy
 
-Keep repository-specific commands, directory conventions, coverage thresholds, CI integration, and reporting services in the project's own test documentation. Before adding a test, inspect that local policy and place the test in the layer that matches its observable scope and runtime cost.
+Complete each item below for this repository. Record the chosen behavior and its boundaries so contributors can select and validate tests consistently.
 
-If the project does not define a layered test suite, use its complete test command for RED and GREEN verification. Do not invent a test hierarchy or coverage gate as part of an unrelated change.
+### 1. Test commands
+
+> TODO: Document the complete test command and any faster commands used during development.
+
+### 2. Test directories or tiers
+
+> TODO: Document the test directories or tiers and the rule for choosing among them.
+
+### 3. Coverage
+
+> TODO: Document how coverage is collected, any thresholds, and whether coverage blocks changes.
+
+### 4. Continuous integration
+
+> TODO: Document which CI checks run tests and which checks are blocking or informational.
+
+### 5. Reporting services
+
+> TODO: Document any external reporting services, badges, or artifacts and whether they affect acceptance.