@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/templates/.agents/README.zh-CN.md

@@ -1,6 +1,6 @@
 # 多 AI 协作指南
 
-本项目支持多个 AI 编程助手协同工作，包括 Claude Code、OpenAI Codex CLI、Gemini CLI、OpenCode 等。
+本项目支持多个 AI 编程助手协同工作，包括 Claude Code、OpenAI Codex CLI、Antigravity CLI、OpenCode 等。
 
 ## 双配置架构
 
@@ -10,7 +10,7 @@
 |---------|---------|---------|
 | Claude Code | `.claude/`（CLAUDE.md、commands/、settings.json） | - |
 | OpenAI Codex CLI | `AGENTS.md` | - |
-| Gemini CLI | `AGENTS.md` | - |
+| Antigravity CLI | `AGENTS.md`、`.agents/skills/` | - |
 | OpenCode | `AGENTS.md` | - |
 | 其他 AI 工具 | `AGENTS.md` | 项目 README |
 
@@ -75,7 +75,7 @@
 
 每个 AI 工具有不同的优势，请据此分配任务：
 
-| 能力 | Claude Code | Codex CLI | Gemini CLI | OpenCode |
+| 能力 | Claude Code | Codex CLI | Antigravity CLI | OpenCode |
 |-----|-------------|-----------|------------|----------|
 | 代码库分析 | 优秀 | 良好 | 优秀 | 良好 |
 | 代码审查 | 优秀 | 良好 | 良好 | 良好 |
@@ -88,7 +88,7 @@
 
 - **分析和审查** - Claude Code（推理能力强，探索全面）
 - **代码实现** - Codex CLI 或 OpenCode（代码生成快，命令式工作流顺手）
-- **大上下文任务** - Gemini CLI（大上下文窗口，适合跨文件分析）
+- **大上下文任务** - Antigravity CLI（大上下文窗口，适合跨文件分析）
 - **命令式迭代** - OpenCode（适合按工作流连续推进）
 
 ## 快速入门
@@ -173,7 +173,7 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 
 当生成的 TUI 命令需要禁用模型调用时，将通用可选字段 `disable-model-invocation` 设为 `true`；各 TUI 适配器按自身能力决定是否消费。多行 `description` 如需保留换行，使用 YAML literal block（`|`）；同步器会为各 TUI 输出对应的多行元数据格式。
 
-新增或修改自定义 skill 后，再执行一次 `update-agent-infra`。同步过程会自动检测非内置 skill，并为 Claude Code、Gemini CLI、OpenCode 生成对应命令。
+新增或修改自定义 skill 后，再执行一次 `update-agent-infra`。同步过程会自动检测非内置 skill，为 Claude Code 和 OpenCode 生成对应命令；Antigravity CLI 则直接发现共享 skill。
 
 ### 共享 skill 源
 
@@ -218,37 +218,41 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 
 `ejected` 条目支持字面路径或 glob，匹配规则与 `merged` 相同。
 
-## 内建 TUI 选择
+## Agent Client 配置
 
-`.agents/.airc.json` 顶层 `tuis` 数组用于决定 agent-infra 应当为哪些内建 TUI（`claude-code`、`codex`、`gemini-cli`、`opencode`）安装并维护命令文件。
+`.agents/.airc.json` 顶层 `agentClients` 数组用于配置全部四个内建客户端（`claude-code`、`codex`、`antigravity-cli`、`opencode`）。每个规范条目包含三个必填字段和一个可选编排策略：
 
-| 取值 | 含义 |
+| 字段 | 含义 |
 |------|------|
-| `tuis` 缺失或为 `null` | 启用全部四个内建 TUI（向后兼容默认，适用于本字段引入之前的 `.airc.json`） |
-| `tuis: []` | 不维护任何内建 TUI。适用于只依赖 `customTUIs`、不需要安装任何内建命令文件的项目 |
-| `tuis: [<子集>]` | 仅维护列出的 TUI；未知 id 会被忽略 |
+| `id` | 内建 Agent Client id。规范数组为每个内建客户端保留且仅保留一个条目。 |
+| `enabled` | agent-infra 是否写入并维护该客户端的项目集成与种子命令。 |
+| `installInSandbox` | 沙箱镜像是否安装该客户端 CLI；此字段与 `enabled` 相互独立。 |
+| `orchestration` | `run-task` 可选默认策略；必须同时提供 executor/reviewer 的 `model` 与宿主原生 `reasoningEffort`，两个角色可以使用同一模型。 |
+
+`run-task` 的显式 model/effort 参数是原子输入：只要提供其中任一字段，就必须完整提供四个 role 字段，不能从配置补齐。完全没有显式策略时，只读取当前客户端的 `orchestration`。模型目录通过 `agent-infra-internal agent-client model-selection --client <id>` 查询，并明确标记 complete、partial 或 interactive-only；局部 override 列表不能当作完整目录。
 
-`ai init` 会通过交互式多选询问该字段：
+无需手工编辑 JSON，可使用：
 
-- 直接回车 = 接受默认值（全部内建 TUI 启用）。
-- 输入逗号分隔的编号或 id（如 `1,3` 或 `claude-code,opencode`）= 只保留子集。
-- 输入 `none` = 明确不启用任何内建 TUI（通常配合后续在 `customTUIs` 添加条目使用）。
-- 非法输入（重复、超界、未知 id、纯空白）会让 init 以非零退出码终止。
+```bash
+ai agent-client list
+ai agent-client status
+ai agent-client enable codex
+ai agent-client disable antigravity-cli
+ai agent-client configure
+```
 
-### 取消某个 TUI 的副作用
+`enable` 和 `disable` 只修改 `enabled`；`configure` 同时编辑两个维度。`ai init` 会询问启用哪些客户端，直接回车会保留界面展示的默认值。所有客户端的 `installInSandbox` 默认均为 `true`。
 
-通过 `ai init` 或手工编辑 `.airc.json` 取消某个内建 TUI 后，下一次 `ai update` / `update-agent-infra` 会：
+旧 `tuis` 字段和 `sandbox.tools` 中的内建客户端 id 仅作为迁移输入。下一次写配置的命令会将其转换为规范 `agentClients` 数组并移除旧字段。若规范配置与旧配置冲突，命令会在修改文件前停止，要求显式解决冲突。
 
-- 跳过该 TUI 的 seed 命令文件写入（例如 `.gemini/commands/<project>/update-agent-infra.toml`）；
-- 在回填 `files.managed` / `files.merged` 时跳过该 TUI owned 的默认条目；
-- **物理清理**该 TUI owned 路径前缀（`.claude/`、`.codex/`、`.gemini/`、`.opencode/`）下的已有文件——清理列表会出现在 `report.managed.removed`，与切换 `platform` 时的清理行为一致。
+### 取消 Agent Client 的副作用
 
-若希望保留某个具体文件，把它加入 `files.ejected`：被 ejected 的、属于已取消 TUI 的条目会保持原状，sync 不会重新创建也不会删除。
+取消某个内建客户端后，协调流程会停止维护其种子命令和 owned 注册项。未修改的生成种子文件可以被删除；本地修改过的种子文件会受到保护并进入报告。`files.ejected` 中的文件仍由项目所有并会被保留。
 
 ### 与其他配置字段的关系
 
-- `tuis` 控制 **agent-infra 写入与维护哪些 TUI 的命令文件**，与 `sandbox.tools`（控制**沙箱镜像里安装哪些 CLI**）相互独立。两者互不影响；`sandbox.tools` 的说明见 Sandbox 一节。
-- `tuis` 与 `customTUIs`（见下）相互独立。取消某个内建 TUI 时 customTUI 命令文件不会被清理，即便 customTUI 的 `dir` 落在该 TUI 的 owned 前缀下（例如 `dir: ".codex/commands"` 的 customTUI 在 `codex` 被取消时仍会保留）。
+- `sandbox.tools` 现在只列出 `agent-infra` 和自定义工具等非客户端工具。内建客户端的安装状态由 `agentClients[].installInSandbox` 表达。
+- `agentClients` 与 `customTUIs`（见下）相互独立。即使自定义 TUI 目录落在已取消的内建客户端路径前缀下，其命令文件也会被保留。
 
 ## 自定义 TUI 配置
 
@@ -300,7 +304,7 @@ disable-model-invocation: true   # 可选；由支持该能力的 TUI 适配器
 
 ## 沙箱自定义工具（Sandbox Custom Tools）
 
-`customTUIs` 只负责生成 slash-command 文件，**不影响沙箱镜像**。如果要把一个非 npm 分发的 CLI 或工具（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像、并 live-mount 它的凭证目录，需要在 `.agents/.airc.json` 的 `sandbox.customTools` 中声明。内建 sandbox 工具（`claude-code` / `codex` / `opencode` / `gemini-cli` / `agent-infra`）行为保持不变；其中 `agent-infra` 只提供沙箱内 `ai` / `agent-infra` CLI，不属于 `tuis` 或 `customTUIs` 配置。
+`customTUIs` 只负责生成 slash-command 文件，**不影响沙箱镜像**。如果要把一个非 npm 分发的 CLI 或工具（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像、并 live-mount 它的凭证目录，需要在 `.agents/.airc.json` 的 `sandbox.customTools` 中声明。内建 Agent Client 按 `agentClients[].installInSandbox` 安装；`agent-infra` 仍是 `sandbox.tools` 中的非客户端条目，只提供沙箱内的 `ai` / `agent-infra` CLI。
 
 ### 必填字段
 

package/templates/.agents/hooks/lifecycle-delegation.js

@@ -0,0 +1,75 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const MAX_INPUT_BYTES = 64 * 1024;
+const localInternalCli = fileURLToPath(new URL('../../dist/bin/internal-cli.js', import.meta.url));
+const clientIndex = process.argv.indexOf('--client');
+const client = clientIndex >= 0 ? process.argv[clientIndex + 1] : '';
+if (client !== 'claude-code') {
+  process.stderr.write('Lifecycle delegation hook requires a supported --client value\n');
+  process.exit(1);
+}
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+  if (Buffer.byteLength(input) > MAX_INPUT_BYTES) {
+    process.stderr.write('Lifecycle delegation hook input exceeds 64 KiB\n');
+    process.exit(1);
+  }
+});
+process.stdin.on('end', () => {
+  let event;
+  try {
+    event = JSON.parse(input || '{}');
+  } catch {
+    process.stderr.write('Lifecycle delegation hook received invalid JSON\n');
+    process.exit(1);
+  }
+  const hook = String(event.hook_event_name || event.event || '').toLowerCase();
+  const nativeAgent = event.agent_name || event.agent_type || event.agent?.name;
+  if (!String(nativeAgent || '').startsWith('agent-infra-lifecycle-')) process.exit(0);
+  const start = hook.includes('start');
+  const stop = hook.includes('stop');
+  if (!start && !stop) {
+    process.stderr.write('Managed lifecycle hook event has an unknown type\n');
+    process.exit(1);
+  }
+  const args = ['task-orchestration', 'auto', start ? 'hook-start' : 'hook-stop', '--client', client];
+  if (start) {
+    args.push(
+      '--native-agent', String(nativeAgent),
+      '--child-id', String(event.child_id || event.agent_id || event.thread_id || ''),
+      '--parent-id', String(event.parent_id || event.parent_session_id || event.session_id || ''),
+      '--spawn-mode', String(event.spawn_mode || (client === 'claude-code' ? 'fresh' : ''))
+    );
+    if (event.model) args.push('--actual-model', String(event.model));
+    const actualEffort = event.actual_reasoning_effort || event.reasoning_effort || event.model_reasoning_effort;
+    if (actualEffort) args.push('--actual-reasoning-effort', String(actualEffort));
+    if (event.model_fallback_reason) args.push('--model-fallback-reason', String(event.model_fallback_reason));
+    if (event.reasoning_effort_fallback_reason) {
+      args.push('--reasoning-effort-fallback-reason', String(event.reasoning_effort_fallback_reason));
+    }
+  } else {
+    args.push(
+      '--native-agent', String(nativeAgent),
+      '--child-id', String(event.child_id || event.agent_id || event.thread_id || '')
+    );
+  }
+  try {
+    const useLocal = existsSync(localInternalCli);
+    const command = useLocal ? process.execPath : 'agent-infra-internal';
+    const commandArgs = useLocal ? [localInternalCli, ...args] : args;
+    const output = execFileSync(command, commandArgs, {
+      encoding: 'utf8',
+      shell: !useLocal && process.platform === 'win32',
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    process.stdout.write(output);
+  } catch (error) {
+    if (error.stdout) process.stdout.write(String(error.stdout));
+    if (error.stderr) process.stderr.write(String(error.stderr));
+    process.exit(typeof error.status === 'number' ? error.status : 1);
+  }
+});

package/templates/.agents/rules/README.en.md

@@ -25,7 +25,9 @@ so you can quickly find "which ones to read" without opening each file.
 ## Task Workflow
 
 - [`task-management.md`](task-management.md) — Task intent detection and workflow-command mapping.
+- [`lifecycle-orchestration.md`](lifecycle-orchestration.md) — Fresh executor/reviewer, one-use receipt, pause/recovery, and safe endpoint rules for `run-task`.
 - [`review-handshake.md`](review-handshake.md) — Three-stage bidirectional review handshake: four-state disposition, symmetric evidence, disagreement ledger, convergence and post-review commit gate.
+- [`review-method.md`](review-method.md) — Shared three-stage review method: multi-pass review, risk lenses, traceability, and finding evidence.
 - [`human-decision-context.md`](human-decision-context.md) — Self-contained context and canonical structure for new human-decision details.
 - [`task-short-id.md`](task-short-id.md) — Resolution, allocation and lifecycle of bare-number short ids.
 - [`milestone-inference.md`](milestone-inference.md) — Milestone inference for create-task / code-task / create-pr.

package/templates/.agents/rules/README.zh-CN.md

@@ -24,7 +24,9 @@
 ## 任务工作流
 
 - [`task-management.md`](task-management.md) — 任务语义识别与工作流命令映射。
+- [`lifecycle-orchestration.md`](lifecycle-orchestration.md) — `run-task` 的 fresh executor/reviewer、一次性 receipt、暂停恢复与安全终点规则。
 - [`review-handshake.md`](review-handshake.md) — 三阶段双向审查握手协议：四态处置、对称证据、分歧账本、收敛与 post-review commit 门禁。
+- [`review-method.md`](review-method.md) — 三阶段共享检视方法：多遍检视、风险镜头、追踪与 finding 证据契约。
 - [`human-decision-context.md`](human-decision-context.md) — 新建人工裁决详情的自足上下文与规范结构。
 - [`task-short-id.md`](task-short-id.md) — 裸数字任务短号的解析、分配与生命周期。
 - [`milestone-inference.md`](milestone-inference.md) — create-task / code-task / create-pr 的 milestone 推断。

package/templates/.agents/rules/commit-and-pr.en.md

@@ -11,6 +11,7 @@
 
 - Never run `git commit` or `git add` automatically
 - Enter the commit workflow only when the user explicitly requests a commit
+- The only exception is a one-use commit authorization issued by an active `run-task` explicitly started by the user. It authorizes this commit round but does not relax staging, sensitive-file, copyright, test, review-snapshot, HEAD/tree, or push gates.
 - After finishing code changes, remind the user to use the appropriate TUI commit command
 
 ## PR Rules

package/templates/.agents/rules/commit-and-pr.zh-CN.md

@@ -11,6 +11,7 @@
 
 - 绝对不要自动执行 `git commit` 或 `git add`
 - 仅在用户明确发起提交命令时才进入提交流程
+- 唯一例外：用户显式启动的 active `run-task` 可签发一次性 commit authorization；它等价于本轮提交授权，但不得放宽暂存、敏感文件、版权、测试、审查快照、HEAD/tree 或 push 门禁。
 - 完成代码修改后，提醒用户使用对应 TUI 的提交命令
 
 ## PR 提交规则

package/templates/.agents/rules/create-issue.github.en.md

@@ -1,10 +1,12 @@
 # Issue Creation
 
+> `--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.
+
 After `create-task` writes task.md, create and initialize the Issue through declarative internal intents:
 
 ```bash
-agent-infra-internal platform-issue create {task-id} --agent {agent}
-agent-infra-internal platform-issue sync {task-id} --agent {agent} --status waiting-for-triage --assignees current --milestone initial --issue-type --fields
+agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status waiting-for-triage --assignees current --milestone initial --issue-type --fields
 ```
 
 The core reads only persisted task identity, title, type, description, and requirements, and reuses deterministic `ai task issue-body` rendering. It owns template selection, upstream/capabilities, duplicate prevention, POST outcome boundaries, response validation, and atomic `issue_number` binding.

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -1,9 +1,11 @@
 # Issue 创建
 
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+
 当 `create-task` 完成本地 `task.md` 落盘后，通过声明式内部命令创建 Issue：
 
 ```bash
-agent-infra-internal platform-issue create {task-id} --agent {agent}
+agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
 ```
 
 命令只从已落盘 task.md 读取身份、标题、类型、描述与需求，并复用 `ai task issue-body` 的确定性正文渲染。它负责模板选择、upstream/capability、已有绑定检查、非幂等 POST 边界、响应身份校验及通过任务写入内核回写 `issue_number`。
@@ -11,7 +13,7 @@ agent-infra-internal platform-issue create {task-id} --agent {agent}
 创建后的初始元数据使用同一适配层同步：
 
 ```bash
-agent-infra-internal platform-issue sync {task-id} --agent {agent} \
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} \
   --status waiting-for-triage --assignees current --milestone initial --issue-type --fields
 ```
 

package/templates/.agents/rules/human-decision-context.en.md

@@ -4,32 +4,34 @@ This rule governs every new `[needs-human-decision]` detail block produced by an
 
 ## Self-contained Context
 
-A maintainer must be able to decide without asking a model to reconstruct context. Every item must state its background, decision objective, impact scope, risks, recommended option, and recommendation rationale. It must provide at least two options, each with both benefits and costs.
+A maintainer must be able to understand the issue and choose without knowing the internal workflow or asking a model to reconstruct context. Start in plain language: explain why a decision is needed now, what must be chosen, which choice is recommended, and why. Then explain what the choice affects and what could go wrong if the wrong choice is made or no action is taken.
+
+Provide at least two options with short names, and state the benefits and trade-offs of each one. Explain internal terms such as stage, severity, and evidence the first time they appear. IDs and evidence are for lookup and troubleshooting; they do not replace the plain-language explanation.
 
 ## Canonical Structure
 
 ```markdown
 ### {AN-N|PL-N|CD-N|HD-N}: {Title} [needs-human-decision]
 
-- **Background**: {facts, constraints, and why a decision is needed}
-- **Decision Objective**: {the single choice that must be made}
-- **Impact Scope**: {affected behavior, files, users, or precedent}
-- **Risks**: {risks of the wrong choice, delay, or no decision}
-- **Recommended Option**: {Option A/B/...}
-- **Recommendation Rationale**: {reason based on benefits, costs, and constraints}
+- **Why a decision is needed now**: {plain-language facts, constraints, and why work cannot simply continue}
+- **What needs a decision**: {the one choice that must be made}
+- **Recommended choice**: {Option A/B/...}
+- **Why this choice**: {reason based on benefits, trade-offs, and current constraints}
+- **What this affects**: {affected behavior, files, users, or future practice}
+- **What could go wrong**: {problems caused by the wrong choice or no action}
 
 #### Option A: {Name}
 
-- **Benefits**: {benefits of this option}
-- **Costs**: {costs and limitations of this option}
+- **Benefits**: {what this option provides}
+- **Trade-offs**: {what this option costs and where it falls short}
 
 #### Option B: {Name}
 
-- **Benefits**: {benefits of this option}
-- **Costs**: {costs and limitations of this option}
+- **Benefits**: {what this option provides}
+- **Trade-offs**: {what this option costs and where it falls short}
 ```
 
-Option C and supporting evidence may be added, but none of the fields above may be omitted or collapsed into an incomparable one-line option list. The heading ID must match the task.md Review Disagreement Ledger row, whose evidence must point to this stable heading anchor.
+Option C and supporting evidence may be added, but none of the information above may be omitted or collapsed into an incomparable one-line option list. The heading ID must match the task.md Review Disagreement Ledger row. Its evidence (the reference used to find the original explanation) must point to this stable heading anchor.
 
 ## Decision Closure
 

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/issue-fields.github.en.md

@@ -1,9 +1,11 @@
 # Issue Fields
 
+> `--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.
+
 Synchronize Issue Type and pinned fields through one intent:
 
 ```bash
-agent-infra-internal platform-issue sync {task-id} --agent {agent} --issue-type --fields
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --issue-type --fields
 ```
 
 Supported task.md mappings are `priority` → `Priority`, `effort` → `Effort`, `start_date` → `Start date`, and `target_date` → `Target date`. The core normalizes localized priority/effort options and validates `YYYY-MM-DD` dates.

package/templates/.agents/rules/issue-fields.github.zh-CN.md

@@ -1,9 +1,11 @@
 # Issue 字段
 
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+
 Issue Type 与 pinned fields 统一由 `platform-issue` intent 动态读取组织 schema 并同步：
 
 ```bash
-agent-infra-internal platform-issue sync {task-id} --agent {agent} --issue-type --fields
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --issue-type --fields
 ```
 
 ## 支持字段

package/templates/.agents/rules/issue-pr-commands.en.md

@@ -1,5 +1,7 @@
 # PR Platform Intents
 
+> `--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.
+
 PR lookup, creation, binding, and metadata synchronization go through typed internal intents. Skills decide branches and write titles/bodies; they do not assemble platform commands.
 
 ## Inspect
@@ -14,7 +16,7 @@ Write the title and body to files, then run:
 
 ```bash
 agent-infra-internal platform-pr create {task-id} \
-  --agent {agent} --base {target-branch} --head {current-branch} \
+  --agent {standard-agent-token} --base {target-branch} --head {current-branch} \
   --title-file {title-file} --body-file {body-file}
 ```
 
@@ -23,7 +25,7 @@ The core performs exact upstream/head/base lookup first. One match is reused, ze
 ## Bind
 
 ```bash
-agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {agent}
+agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {standard-agent-token}
 ```
 
 Conflicting bindings fail without changing `task.md`.
@@ -32,7 +34,7 @@ Conflicting bindings fail without changing `task.md`.
 
 ```bash
 agent-infra-internal platform-pr sync {task-id} \
-  --agent {agent} --metadata --closing-issue
+  --agent {standard-agent-token} --metadata --closing-issue
 ```
 
 The core copies type / `in:` labels, assignee, a specific milestone, and the closing association from the linked Issue. Permission-bound operations report `skipped` under top-level `degraded`; the Issue is never updated in reverse.

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

@@ -1,5 +1,7 @@
 # PR Platform Intents
 
+> `--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.
+
 PR lookup, creation, binding, and metadata synchronization go through typed internal intents. Skills decide branches and write titles/bodies; they do not assemble platform commands.
 
 ## Inspect
@@ -12,7 +14,7 @@ agent-infra-internal platform-pr inspect {task-id}
 
 ```bash
 agent-infra-internal platform-pr create {task-id} \
-  --agent {agent} --base {target-branch} --head {current-branch} \
+  --agent {standard-agent-token} --base {target-branch} --head {current-branch} \
   --title-file {title-file} --body-file {body-file}
 ```
 
@@ -21,10 +23,10 @@ The core performs exact upstream/head/base lookup. One match is reused, zero cre
 ## Bind and synchronize
 
 ```bash
-agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {agent}
+agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {standard-agent-token}
 
 agent-infra-internal platform-pr sync {task-id} \
-  --agent {agent} --metadata --closing-issue
+  --agent {standard-agent-token} --metadata --closing-issue
 ```
 
 Conflicting bindings do not change `task.md`. Metadata comes from the linked Issue, permission-bound items degrade independently, and an already-created PR is never rolled back.

package/templates/.agents/rules/issue-pr-commands.github.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 资源的定位、创建、绑定和元数据同步统一通过 typed internal intent；SKILL 只负责决定分支、标题、正文和调用时机，不直接拼装平台命令。
 
 ## 定位
@@ -16,7 +18,7 @@ agent-infra-internal platform-pr inspect {task-id}
 
 ```bash
 agent-infra-internal platform-pr create {task-id} \
-  --agent {agent} --base {target-branch} --head {current-branch} \
+  --agent {standard-agent-token} --base {target-branch} --head {current-branch} \
   --title-file {title-file} --body-file {body-file}
 ```
 
@@ -25,7 +27,7 @@ core 会先按 upstream、head 和 base 精确定位；唯一既有 PR 会复用
 ## 显式绑定
 
 ```bash
-agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {agent}
+agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {standard-agent-token}
 ```
 
 冲突绑定稳定失败且不修改 `task.md`。
@@ -34,7 +36,7 @@ agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {agent}
 
 ```bash
 agent-infra-internal platform-pr sync {task-id} \
-  --agent {agent} --metadata --closing-issue
+  --agent {standard-agent-token} --metadata --closing-issue
 ```
 
 core 从关联 Issue 复制 type / `in:` labels、assignee、具体 milestone，并确保 closing association。权限不足返回逐项 `skipped` 和顶层 `degraded`；不得反向修改 Issue。

package/templates/.agents/rules/issue-pr-commands.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 资源的定位、创建、绑定和元数据同步统一通过 typed internal intent；SKILL 只负责决定分支、标题、正文和调用时机，不直接拼装平台命令。
 
 ## 定位
@@ -16,7 +18,7 @@ agent-infra-internal platform-pr inspect {task-id}
 
 ```bash
 agent-infra-internal platform-pr create {task-id} \
-  --agent {agent} --base {target-branch} --head {current-branch} \
+  --agent {standard-agent-token} --base {target-branch} --head {current-branch} \
   --title-file {title-file} --body-file {body-file}
 ```
 
@@ -25,7 +27,7 @@ core 会先按 upstream、head 和 base 精确定位；唯一既有 PR 会复用
 ## 显式绑定
 
 ```bash
-agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {agent}
+agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {standard-agent-token}
 ```
 
 冲突绑定稳定失败且不修改 `task.md`。
@@ -34,7 +36,7 @@ agent-infra-internal platform-pr bind {task-id} --pr {pr-number} --agent {agent}
 
 ```bash
 agent-infra-internal platform-pr sync {task-id} \
-  --agent {agent} --metadata --closing-issue
+  --agent {standard-agent-token} --metadata --closing-issue
 ```
 
 core 从关联 Issue 复制 type / `in:` labels、assignee、具体 milestone，并确保 closing association。权限不足返回逐项 `skipped` 和顶层 `degraded`；不得反向修改 Issue。

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

@@ -1,5 +1,7 @@
 # Issue Sync
 
+> `--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.
+
 ## Marker Registry
 
 | Key | Marker |
@@ -10,13 +12,15 @@
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
 
+`pr-review` content is synced only as an Issue artifact comment (via the `artifact` / `artifactChunk` markers) and is never a `restore-task` recovery source; restore still accepts only an Issue number and reads only registered Issue markers, with no PR source.
+
 Comments use `platform-comment`; Issue resources use `platform-issue`:
 
 ```bash
 agent-infra-internal platform-issue inspect {task-id}
-agent-infra-internal platform-issue create {task-id} --agent {agent}
-agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {agent}
-agent-infra-internal platform-issue sync {task-id} --agent {agent} {desired-state-flags}
+agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
+agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {standard-agent-token}
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} {desired-state-flags}
 ```
 
 The core owns status/in labels, assignees, milestones, Issue Type, pinned fields, requirements, state, capabilities, dry-run, retries, errors, and idempotency. Omitted flags preserve values; `none` explicitly clears them. Status labels converge to at most one, and ambiguous requirement identity fails closed.

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

@@ -1,5 +1,7 @@
 # Issue 同步规则
 
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+
 ## Marker 注册表
 
 以下 key 及格式是 Issue 评论身份的兼容契约；调用方只传 key/资源，不自行拼 marker。
@@ -14,6 +16,8 @@
 
 `prSummary` 属于 `.agents/rules/pr-sync.md`，本规则不实现 PR 聚合。
 
+`pr-review` 原文只通过 `artifact` / `artifactChunk` marker 同步为 Issue artifact 评论，不作为 `restore-task` 恢复来源；恢复仍只接受 Issue 编号并只读注册的 Issue marker，不新增 PR 来源。
+
 ## 平台 intent
 
 GitHub upstream、认证、capability、分页、marker 查找、幂等 create/update、分片、重试与错误分类由 typed platform core 统一处理：
@@ -23,7 +27,7 @@ agent-infra-internal platform-context resolve [--cwd <path>]
 agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
 agent-infra-internal platform-comment owner <task-ref>
 agent-infra-internal platform-comment sync <task-ref> \
-  --kind task|artifact|summary|cancel --agent <agent> \
+  --kind task|artifact|summary|cancel --agent <standard-agent-token> \
   [--artifact <canonical.md>] [--body-file <path|->] [--backfill]
 ```
 
@@ -54,9 +58,9 @@ agent-infra-internal task-warning {task-id} add \
 
 ```bash
 agent-infra-internal platform-issue inspect {task-id}
-agent-infra-internal platform-issue create {task-id} --agent {agent}
-agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {agent}
-agent-infra-internal platform-issue sync {task-id} --agent {agent} {desired-state-flags}
+agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
+agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {standard-agent-token}
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} {desired-state-flags}
 ```
 
 `sync` 支持 status/in labels、assignee、milestone、Issue Type、pinned fields、需求复选框与 Issue state。省略 flag 表示 preserve，`none` 表示显式清空。适配层统一处理集合差集、动态 schema、权限降级、dry-run、重试、错误分类与幂等重放；SKILL 不得拼装 `gh issue`、GraphQL 或权限分支。

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

@@ -0,0 +1,24 @@
+# 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. A v2 run persists complete policy, source, and append-only recovery history. Only a v1 run with no pending delegation and zero receipts may be upgraded in place after supplying a complete policy; any historical receipt stays paused because effort is unverifiable. Migration is forward-only: old binaries must not advance active v2 runs.
+
+## Model Policy
+
+- A new run persists model and reasoning effort for both roles. Explicit policy is atomic across all four role fields; only a fully absent explicit policy may fall back to the current client's `agentClients[].orchestration`.
+- Route resolves requested model/effort by role, and prepare matches both before snapshotting. Native spawn must not inherit session defaults.
+- Native start records host-observed actual model/effort. Each mismatch needs its own fallback reason, and requested values must never be fabricated as actual evidence.
+- Model selection is labeled as a complete catalog, partial catalog, or interactive-only guidance; a local override enum must not be presented as complete.
+
+## 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.