@fitlab-ai/agent-infra 0.9.1 → 0.9.3

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

@@ -0,0 +1,24 @@
+# 通用规则 - 生命周期总控
+
+## 保证边界
+
+- 总控只路由和委派；阶段技能仍是业务规则与产物格式的单一事实源。
+- 每个阶段和每轮返工都创建 fresh executor；每轮审查创建 fresh reviewer，禁止 follow-up 复用。
+- reviewer 只能写当前审查产物和核心生成的任务元数据。业务代码、HEAD 或暂存区变化会使 receipt 失效。
+- active run 中只有一个 pending delegation。缺失、错配、fork、重放、hook 不可用或工作区漂移一律暂停。
+- 首版成功终点是一次通过既有安全门禁的 `commit`；不创建 PR、不监控 checks、不执行 `complete-task`。
+
+## 恢复语义
+
+`orchestration.json` 是详细状态源。v2 run 保存完整策略、来源与 append-only 恢复历史。只有无 pending delegation 且零历史 receipt 的 v1 run 可在补齐完整策略后原地升级；任一历史 receipt 因缺 effort 证据保持暂停。其他阻塞、未封存 receipt 或基线漂移继续保持暂停。迁移是 forward-only，旧二进制不得推进 v2 active run。
+
+## 模型策略
+
+- 新 run 必须固化 executor/reviewer 各自的 model 与 reasoning effort；显式策略必须四字段原子完整，完全没有显式字段时才读取当前 client 的 `agentClients[].orchestration`。重入不得静默改写策略。
+- route 按 role 返回 requested model/effort，prepare 必须在工作区快照前精确匹配两者；原生 spawn 不能继承会话默认值。
+- 原生 start 必须记录宿主观察到的 actual model/effort。任一字段与 requested 不同时必须记录独立 fallback reason；requested 值不得补造 actual 证据。
+- 模型选择能力必须标记 complete catalog、partial catalog 或 interactive-only guidance；局部 override 枚举不得冒充完整目录。
+
+## 稳定暂停条件
+
+人工裁决、人工验证、握手或总步骤上限、权限/网络失败、用户工作区冲突、客户端 capability 不支持及未知 hook schema 都持久化为暂停原因。总控不得中途询问或降级为同上下文自审。

package/templates/.agents/rules/milestone-inference.github.en.md

@@ -1,13 +1,15 @@
 # Milestone Inference
 
+> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+
 Milestones narrow through declarative Issue intents:
 
 ```bash
 # create/import phase
-agent-infra-internal platform-issue sync {task-id} --agent {agent} --milestone initial
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone initial
 
 # code phase
-agent-infra-internal platform-issue sync {task-id} --agent {agent} --milestone specific
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone specific
 ```
 
 `initial` prefers a valid task milestone, otherwise the lowest open `X.Y.x`, then `General Backlog`. `specific` narrows a release line to the highest open patch version using main/release-line ancestry. Missing facts or triage permission preserve the remote value and return skipped/degraded. `create-pr` reuses the Issue milestone in the 09/10 PR adapter.

package/templates/.agents/rules/milestone-inference.github.zh-CN.md

@@ -1,11 +1,13 @@
 # Milestone 推断规则
 
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+
 Milestone 继续按生命周期逐步收窄，但候选读取、分支判断、权限降级和写入统一由 `platform-issue` 处理。
 
 ## 阶段 1：创建或导入
 
 ```bash
-agent-infra-internal platform-issue sync {task-id} --agent {agent} --milestone initial
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone initial
 ```
 
 优先使用 task.md 中存在且有效的显式 milestone；否则从 open milestones 选择最低 `X.Y.x` 版本线，最后回退 `General Backlog`。`triage=false` 或外部事实不足时保持远端值并返回 skipped/degraded。
@@ -13,7 +15,7 @@ agent-infra-internal platform-issue sync {task-id} --agent {agent} --milestone i
 ## 阶段 2：`code-task`
 
 ```bash
-agent-infra-internal platform-issue sync {task-id} --agent {agent} --milestone specific
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone specific
 ```
 
 版本线收窄规则保持不变：主干模式在当前版本线取最高 patch；多版本分支模式依据 release-line/main 祖先关系选择版本线。无法可靠判断时保持原值。完成门禁仍拒绝 `X.Y.x`。

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

@@ -20,6 +20,24 @@ 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}] \
+  [--version {version}]
+```
+
+- Pass the next skill name for the already-selected scenario. Include `--task-ref` only when that command needs a task reference.
+- Include `--version` only for a versioned release command. It must start with a digit and satisfy `semver.valid(raw) === raw`; never pass an action, complete command, shell fragment, whitespace, or a `v` / `V` / `=` prefix.
+- 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,24 @@
 - **「任务信息」/「任务状态」结构化字段行** → 完整 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}] \
+  [--version {version}]
+```
+
+- 静态传入当前已选场景的下一 skill 名；只有命令需要任务引用时才传 `--task-ref`。
+- 只有版本化发布命令需要版本时才传 `--version`；值必须是以数字开头且 `semver.valid(raw) === raw` 的规范 SemVer。不得传 action、完整命令、shell 片段、空白或 `v` / `V` / `=` 前缀。
+- 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

@@ -39,6 +39,23 @@ SKILLs currently covered by this exemption:
 
 - `analyze-task`: when the task description/requirements are insufficient for a reliable analysis, it may ask questions one at a time at the entry point to converge the requirements
 
+### Exemption 4: Remote-publish authorization for the current snapshot
+
+After preparation in the current session and presentation of the latest snapshot or exact content, one question may ask whether to perform that remote publish. Authorization never carries across sessions or snapshots. Denial, adjustment, a question, ambiguity, or interruption fails closed without a remote write.
+
+SKILLs currently covered by this exemption:
+
+- `release`: may confirm publish after presenting the latest release snapshot
+- `create-release-note`: may confirm publish after presenting exact staged notes and their digest
+
+### Exemption 5: Complete model policy missing at lifecycle start
+
+Only when `run-task` receives `ORCHESTRATION_MODEL_POLICY_REQUIRED` before any run, baseline, receipt, or child is created may it show model-selection context with its completeness label and ask once for complete executor/reviewer model + reasoning effort. Partial explicit policy, a missing client, active delegation, and other pause causes do not qualify. No answer means no run is created.
+
+SKILLs currently covered by this exemption:
+
+- `run-task`: may collect only the atomic model policy explicitly required by core
+
 ## No-Mid-Flow-Questions Clause (default behavior)
 
 For every SKILL execution context not covered by any exemption above, the default behavior is:
@@ -78,6 +95,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

@@ -39,6 +39,23 @@
 
 - `analyze-task`：任务描述/需求信息不足以支撑可靠分析时，可在入口处逐个提问收敛需求
 
+### 例外 4：当前快照的远端发布授权
+
+仅允许在当前会话已完成准备、已展示待发布的最新快照或精确内容后，询问一次是否执行对应远端发布。确认不跨会话、不跨快照复用；否定、调整、疑问、歧义或中断均 fail closed，不得写入远端。
+
+当前归入本例外的 SKILL：
+
+- `release`：展示最新 release snapshot 后确认是否 publish
+- `create-release-note`：展示 stage 后的精确 notes 与摘要后确认是否 publish
+
+### 例外 5：生命周期启动缺少完整模型策略
+
+仅当 `run-task` 在创建任何 run、baseline、receipt 或 child 之前收到核心错误 `ORCHESTRATION_MODEL_POLICY_REQUIRED` 时，可展示带完整性标签的模型选择上下文，并一次询问 executor/reviewer 的完整 model + reasoning effort。部分显式策略、缺少 client、active delegation 或其他暂停原因不适用；用户未回答时不得创建 run。
+
+当前归入本例外的 SKILL：
+
+- `run-task`：仅补齐核心明确要求的原子模型策略
+
 ## 禁言条款（默认行为）
 
 不属于上述任一例外的所有 SKILL 执行场景，遵循以下默认行为：
@@ -78,6 +95,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/pr-checks-commands.en.md

@@ -1,6 +1,6 @@
-# Required-checks Platform Intents
+# PR Readiness Platform Intents
 
-Typed intents own required-only selection, polling deadlines, run/job resolution, and log retrieval. The skill/model owns failure classification, root-cause analysis, minimum fixes, tests, and authorized commit/push actions.
+Typed intents own required-check selection, PR mergeability, polling deadlines, run/job resolution, and logs. Every inspect/poll aggregates facts from one PR head snapshot; facts are never mixed across heads.
 
 ```bash
 agent-infra-internal platform-checks inspect {task-id}
@@ -15,4 +15,4 @@ agent-infra-internal platform-checks logs {task-id} \
   --run {run-id} [--job {job-id}]
 ```
 
-`checks.state` is `passed|failed|pending|timed-out|cancelled|no-required`. Green/no-required exits 0; definite failure/cancellation exits 1; pending, timeout, or network blocking exits 2. Each platform adapter validates its own dependencies before operations and preserves dependency or deterministic platform errors without compatibility degradation. Run resolution prefers a validated details URL and otherwise requires one exact PR-head/check-name match. Platform intents never edit business code or push.
+`readiness.state` is `ready|conflicting|checks-failed|pending|timed-out|cancelled` and carries `headSha`. Only `ready` exits 0; conflicting/check failures exit 1; all other readiness or network blocking exits 2. `checks.state` remains available as check-only diagnostics. Adapter dependency and deterministic platform errors are preserved without degradation. Platform intents never edit business code or push.

package/templates/.agents/rules/pr-checks-commands.github.en.md

@@ -1,4 +1,4 @@
-# Required-checks Platform Intents
+# GitHub PR Readiness Intents
 
 The GitHub adapter requires `gh >= 2.16.0`. Platform context checks this dependency before any GitHub API, PR, or checks operation. Projects that do not select GitHub neither probe nor depend on `gh`.
 
@@ -15,4 +15,4 @@ agent-infra-internal platform-checks logs {task-id} \
   --run {run-id} [--job {job-id}]
 ```
 
-The core owns required-only selection, deadlines, exact run/job resolution, and faithful logs. Green/no-required exits 0; definite failure exits 1; pending, timeout, or network blocking exits 2. Missing dependencies, unsupported versions, and deterministic platform failures preserve their structured errors without compatibility degradation. The skill/model still owns diagnosis, fixes, tests, and authorized commit/push actions.
+The adapter normalizes REST `mergeable=false` to `conflicting`, null/missing to `unknown`, and true to `mergeable`; `mergeable=true` plus diagnostic `dirty` is contradictory and becomes `unknown`. Other diagnostics such as `blocked` do not override REST true. Core combines that fact with required checks for one `headSha`: only `ready` exits 0, `conflicting|checks-failed` exit 1, and pending/timeout/cancel/network blocking exit 2. Dependency and deterministic platform errors are preserved without degradation.

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

@@ -1,4 +1,4 @@
-# PR required checks 平台意图
+# GitHub PR readiness 平台意图
 
 required checks 的筛选、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。SKILL/模型只负责失败分类、根因分析、最小修复和授权后的提交推送。
 
@@ -13,7 +13,7 @@ agent-infra-internal platform-checks watch {task-id} \
   --interval-seconds 30 --deadline-seconds 1800
 ```
 
-结构化 `checks.state` 为 `passed|failed|pending|timed-out|cancelled|no-required`。`passed|no-required` 退出 0；确定失败/取消退出 1；pending、timeout 或网络阻塞退出 2。依赖缺失、版本过低和确定性平台错误直接返回其原始结构化错误，不执行兼容降级。
+adapter 把 REST `mergeable=false` 规范化为 `conflicting`，null/缺失为 `unknown`，true 为 `mergeable`；true 与诊断 `dirty` 矛盾时降为 `unknown`。`blocked` 等其他诊断不覆盖 REST true。core 在同一 `headSha` 上与 required checks 聚合：仅 `ready` 退出 0，`conflicting|checks-failed` 退出 1，pending/timeout/cancel/网络阻塞退出 2。依赖与确定性平台错误不降级。
 
 ## 定位失败 run/job
 

package/templates/.agents/rules/pr-checks-commands.zh-CN.md

@@ -1,6 +1,6 @@
-# PR required checks 平台意图
+# PR readiness 平台意图
 
-required checks 的筛选、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。SKILL/模型只负责失败分类、根因分析、最小修复和授权后的提交推送。
+required checks、PR mergeability、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。每次 inspect/poll 都在同一 PR head 快照上聚合，不跨 head 拼接事实。
 
 ## 快照与监控
 
@@ -11,7 +11,7 @@ agent-infra-internal platform-checks watch {task-id} \
   --interval-seconds 30 --deadline-seconds 1800
 ```
 
-结构化 `checks.state` 为 `passed|failed|pending|timed-out|cancelled|no-required`。`passed|no-required` 退出 0；确定失败/取消退出 1；pending、timeout 或网络阻塞退出 2。平台 adapter 必须在操作前验证自身依赖；依赖或确定性平台错误直接透传，不执行兼容降级。
+结构化 `readiness.state` 为 `ready|conflicting|checks-failed|pending|timed-out|cancelled`，并携带 `headSha`。仅 `ready` 退出 0；`conflicting|checks-failed` 退出 1；其余或网络阻塞退出 2。`checks.state` 仍保留 check-only 诊断；平台 adapter 的依赖和确定性错误不降级。
 
 ## 定位失败 run/job
 

package/templates/.agents/rules/pr-sync.en.md

@@ -1,5 +1,7 @@
 # PR Summary Synchronization
 
+> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+
 The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, the marker, current HEAD, paginated comment lookup, and create/update/no-op reconciliation.
 
 ## Inputs
@@ -16,7 +18,7 @@ Write only the summary body to a file, without marker or SHA:
 
 ```bash
 agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {agent} --body-file {summary-body-file}
+  --agent {standard-agent-token} --body-file {summary-body-file}
 ```
 
 The core wraps `<!-- sync-pr:{task-id}:summary -->` and current `<!-- last-commit: ... -->`, then creates, updates in place, or returns no-op. Duplicate markers fail deterministically. Callers never assemble shell/heredoc comment commands.

package/templates/.agents/rules/pr-sync.github.en.md

@@ -1,12 +1,22 @@
 # PR Summary Synchronization
 
+> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+
 The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, marker/HEAD wrapping, paginated comment lookup, and reconciliation.
 
+## Three-Layer Isolation
+
+- `sync-pr:{task-id}:summary` (`platform-pr summary-sync`) is an updatable reviewer summary; it is neither a process copy nor a formal Review.
+- The full `pr-review*` process copy lives in the Issue artifact comment (`platform-comment sync --kind artifact`) and is restored by `restore-task` under its Issue-only contract.
+- A formal PR Review (`platform-pr-review publish`) is the only formal conclusion carrier published to the PR, bound to the reviewed head SHA, and includes conclusion, findings, receipt, and the Issue artifact link.
+
+The three never cross: a regular PR comment does not carry the full process copy; an Issue artifact comment is not treated as a formal Review; a summary is not presented as a formal Review.
+
 ```bash
 agent-infra-internal platform-pr summary-context {task-id}
 
 agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {agent} --body-file {summary-body-file}
+  --agent {standard-agent-token} --body-file {summary-body-file}
 ```
 
 Use only canonical inputs returned by the context command. Write the plain body without marker or SHA. The core owns `<!-- sync-pr:{task-id}:summary -->`, current `<!-- last-commit: ... -->`, create/update/no-op behavior, and duplicate-marker conflicts. Summary failure never rolls back a PR or commit.

package/templates/.agents/rules/pr-sync.github.zh-CN.md

@@ -1,7 +1,17 @@
 # PR 摘要同步
 
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+
 PR 摘要的语义聚合由模型完成；canonical 产物选择、marker、当前 HEAD、分页评论查找和 create/update/no-op 由 typed core 负责。
 
+## 三层隔离
+
+- `sync-pr:{task-id}:summary`（`platform-pr summary-sync`）是可更新的 reviewer 摘要，不是过程原文，也不是正式 Review。
+- `pr-review*` 完整过程原文在 Issue artifact 评论（`platform-comment sync --kind artifact`），由 `restore-task` 按 Issue-only 契约恢复。
+- 正式 PR Review（`platform-pr-review publish`）是唯一发布到 PR 的正式结论载体，绑定被审 head SHA，含结论、finding、receipt 与 Issue artifact 链接。
+
+三者不串用：PR 普通评论不承载完整过程原文；Issue artifact 评论不当作正式 Review；摘要不冒充正式 Review。
+
 ## 聚合输入
 
 ```bash
@@ -35,7 +45,7 @@ core 最终包装出的 canonical 评论结构为：
 
 ```bash
 agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {agent} --body-file {summary-body-file}
+  --agent {standard-agent-token} --body-file {summary-body-file}
 ```
 
 core 会包装唯一 `<!-- sync-pr:{task-id}:summary -->` 和当前 `<!-- last-commit: ... -->`，分页查找 PR 普通评论：不存在则创建、正文变化则原地更新、无差异则 no-op、重复 marker 则稳定失败。正文通过文件输入，调用方不得拼 shell/heredoc。

package/templates/.agents/rules/pr-sync.zh-CN.md

@@ -1,5 +1,7 @@
 # PR 摘要同步
 
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+
 PR 摘要的语义聚合由模型完成；canonical 产物选择、marker、当前 HEAD、分页评论查找和 create/update/no-op 由 typed core 负责。
 
 ## 聚合输入
@@ -23,7 +25,7 @@ agent-infra-internal platform-pr summary-context {task-id}
 
 ```bash
 agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {agent} --body-file {summary-body-file}
+  --agent {standard-agent-token} --body-file {summary-body-file}
 ```
 
 core 会包装唯一 `<!-- sync-pr:{task-id}:summary -->` 和当前 `<!-- last-commit: ... -->`，分页查找 PR 普通评论：不存在则创建、正文变化则原地更新、无差异则 no-op、重复 marker 则稳定失败。正文通过文件输入，调用方不得拼 shell/heredoc。

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

@@ -2,4 +2,4 @@
 
 This code platform does not provide a release-note adapter.
 
-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.
+Local `agent-infra-internal platform-release-notes stage --notes-file "{notes-file}"` still normalizes an external file and returns its digest. Use `context` to receive a structured `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op and do not probe another platform client. Publish with `--expected-sha256` remains a no-op until an adapter is provided.

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

@@ -6,17 +6,33 @@ Release-note platform operations use a typed internal intent. Callers consume st
 
 ```bash
 agent-infra-internal platform-release-notes context \
-  --from-tag "v{prev-version}" --to-tag "v{version}" \
-  --branch "{branch}" --history-limit 3
+  --from-tag "v{prev-version}" \
+  --to-tag "v{version}" \
+  --branch "{branch}" \
+  --history-limit 3
 ```
 
-The result contains release history, pull requests, closing Issues, and normalized contributor identities. Unsupported platforms return a stable `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op.
+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.
+
+## Stage Release Notes
+
+```bash
+agent-infra-internal platform-release-notes stage \
+  --notes-file "{notes-file}"
+```
+
+The command accepts only an external regular file, normalizes it atomically, and returns SHA-256 for its exact bytes.
 
 ## Publish Release Notes
 
+Call this only after user confirmation:
+
 ```bash
 agent-infra-internal platform-release-notes publish \
-  --tag "v{version}" --title "v{version}" --notes-file "{notes-file}"
+  --tag "v{version}" \
+  --title "v{version}" \
+  --notes-file "{notes-file}" \
+  --expected-sha256 "{preview-sha256}"
 ```
 
-The command updates an existing Release or creates a missing one. `--dry-run` only plans the operation. Exit codes `0/1/2` mean success, failure, and blocked.
+The command recomputes the digest before platform access and performs no platform write on mismatch. On a match it 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

@@ -6,17 +6,33 @@
 
 ```bash
 agent-infra-internal platform-release-notes context \
-  --from-tag "v{prev-version}" --to-tag "v{version}" \
-  --branch "{branch}" --history-limit 3
+  --from-tag "v{prev-version}" \
+  --to-tag "v{version}" \
+  --branch "{branch}" \
+  --history-limit 3
 ```
 
-结果包含历史发布、PR、关联 Issue 和规范化贡献者身份。不支持的平台返回稳定的 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op。
+结果包含 `history`、`pullRequests`、`closingIssues` 和带规范化 `login` / `resolution` 的 commit `authors`。`status: no-op` 且错误码为 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` 表示当前平台不支持远端发布说明能力。
+
+## Stage Release notes
+
+```bash
+agent-infra-internal platform-release-notes stage \
+  --notes-file "{notes-file}"
+```
+
+命令只接受工作树外普通文件，原子规范化并返回精确 bytes 的 SHA-256。
 
 ## 发布 Release notes
 
+用户确认后调用：
+
 ```bash
 agent-infra-internal platform-release-notes publish \
-  --tag "v{version}" --title "v{version}" --notes-file "{notes-file}"
+  --tag "v{version}" \
+  --title "v{version}" \
+  --notes-file "{notes-file}" \
+  --expected-sha256 "{preview-sha256}"
 ```
 
-命令更新既有 Release，缺失时创建；`--dry-run` 只规划操作。退出码 `0/1/2` 分别表示成功、失败和阻塞。
+命令在平台访问前复算摘要，不匹配时零写入；匹配时更新已有 Release，缺失时创建。`--dry-run` 只返回 planned operation。退出码为 `0` 时成功，`1` 表示稳定失败，`2` 表示网络或平台阻塞。

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

@@ -2,4 +2,4 @@
 
 当前代码平台未提供发布说明 adapter。
 
-调用 `agent-infra-internal platform-release-notes context` 会返回结构化的 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op，不得探测其他平台 client。在提供 adapter 前，发布操作同样保持 no-op。
+本地 `agent-infra-internal platform-release-notes stage --notes-file "{notes-file}"` 仍可规范化工作树外文件并返回摘要。调用 `context` 会返回结构化的 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op，不得探测其他平台 client；提供 adapter 前，带 `--expected-sha256` 的 publish 同样保持 no-op。

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

@@ -84,16 +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`. The only automatic exception is a bound merged GitHub PR whose platform snapshot proves B is the original PR head, whose merge commit is in local HEAD history, whose reviewed changes exactly match the normalized patch of a single-parent squash commit, and whose protected paths have no later commits. Missing platform or Git evidence 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 strict / squash-equivalent relation above independently.
+- 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,16 +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`。唯一自动例外是绑定 GitHub PR 已合并，且平台快照证明 B 是原 PR head、merge commit 位于本地 HEAD 历史中、受审查变更与单父 squash commit 的规范化补丁完全一致，并且 merge 后受保护路径没有新提交；缺少任一平台或 Git 证据时 fail closed。
-- required checks 由合并前的分支保护 / ruleset 与 `review-code` / `watch-pr` 路由负责。post-review-commit 仍独立执行上述严格 / squash 等价判定。
+- 若 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.