@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -73,7 +73,7 @@
     "typescript": "~7.0"
   },
   "optionalDependencies": {
-    "@lydell/node-pty": "^1.2.0-beta.12"
+    "@lydell/node-pty": "^1.2.0-beta.14"
   },
   "overrides": {
     "axios": "1.18.1"

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

@@ -218,37 +218,38 @@ Ordinary `managed` files keep their overwrite semantics. A small set of platform
 
 `ejected` entries support literal paths or globs, using the same matching rules as `merged`.
 
-## Built-in TUI Selection
+## Agent Client Configuration
 
-Use the top-level `.agents/.airc.json` `tuis` array to pick which built-in TUIs (`claude-code`, `codex`, `gemini-cli`, `opencode`) agent-infra should install command files for and keep in sync.
+Use the top-level `.agents/.airc.json` `agentClients` array to configure all four built-in clients (`claude-code`, `codex`, `gemini-cli`, `opencode`). Each canonical entry has three fields:
 
-| Value | Meaning |
+| Field | Meaning |
 |-------|---------|
-| `tuis` missing or `null` | All four built-in TUIs are enabled (backward-compatible default for legacy `.airc.json` predating this field). |
-| `tuis: []` | No built-in TUI is managed. Use this when the project only relies on `customTUIs` and does not need any built-in command files installed. |
-| `tuis: [<subset>]` | Only the listed TUIs are managed. Unknown ids are ignored. |
+| `id` | Built-in Agent Client id. The canonical array contains exactly one entry for each built-in client. |
+| `enabled` | Whether agent-infra writes and maintains that client's project integration and seed command. |
+| `installInSandbox` | Whether the sandbox image installs that client's CLI. This is independent from `enabled`. |
 
-`ai init` includes an interactive multi-select for this field:
+Manage these settings without hand-editing JSON:
 
-- Press Enter to accept the default (all built-in TUIs enabled).
-- Type comma-separated numbers or ids (e.g. `1,3` or `claude-code,opencode`) to keep a subset.
-- Type `none` to explicitly disable every built-in TUI (typically combined with a `customTUIs` entry added later).
-- Invalid input (duplicate, out-of-range, unknown id, whitespace-only) aborts init with a non-zero exit code.
+```bash
+ai agent-client list
+ai agent-client status
+ai agent-client enable codex
+ai agent-client disable gemini-cli
+ai agent-client configure
+```
 
-### Side effects of disabling a TUI
+`enable` and `disable` only change `enabled`; `configure` edits both dimensions. `ai init` asks which clients to enable and preserves the displayed defaults when you press Enter. All clients default to `installInSandbox: true`.
 
-When you disable a built-in TUI (either via `ai init` or by hand-editing `.airc.json`), the next `ai update` / `update-agent-infra` will:
+Legacy `tuis` and built-in client ids in `sandbox.tools` are migration inputs only. The next config-writing command converts them into the canonical `agentClients` array and removes the legacy fields. If canonical and legacy values conflict, the command stops without modifying files so the conflict can be resolved explicitly.
 
-- skip seed command writes for that TUI (e.g. `.gemini/commands/<project>/update-agent-infra.toml`);
-- skip the TUI's owned default entries when backfilling `files.managed` / `files.merged`;
-- **clean up existing files** under the TUI's owned path prefix (`.claude/`, `.codex/`, `.gemini/`, `.opencode/`) — these are listed in `report.managed.removed`, mirroring the cleanup behavior when switching `platform`.
+### Side effects of disabling an Agent Client
 
-To opt a specific file out of this cleanup, list it in `files.ejected`; ejected entries owned by disabled TUIs are preserved as-is and are not re-created by sync.
+When you disable a built-in client, reconciliation stops maintaining its seed command and owned registry entries. An unchanged generated seed may be removed; a locally modified seed is protected and reported instead. Files listed in `files.ejected` remain project-owned and are preserved.
 
 ### Relation to other config fields
 
-- `tuis` controls **which TUI command files agent-infra writes and maintains**. It is independent from `sandbox.tools`, which controls **which CLIs the sandbox image installs**. Toggling one does not affect the other; the README for `sandbox.tools` lives in the Sandbox section.
-- `tuis` is independent from `customTUIs` (see below). CustomTUI command files are not removed when you disable a built-in TUI, even if the customTUI's `dir` falls under that TUI's owned prefix (e.g. a customTUI configured with `dir: ".codex/commands"` is preserved when `codex` is disabled).
+- `sandbox.tools` now lists non-client tools such as `agent-infra` and custom tools. Built-in client installation belongs in `agentClients[].installInSandbox`.
+- `agentClients` is independent from `customTUIs` (see below). Custom TUI command files are preserved even when their directory is under a disabled built-in client's path prefix.
 
 ## Custom TUI Configuration
 
@@ -300,7 +301,7 @@ Namespaced custom TUI:
 
 ## Sandbox Custom Tools
 
-`customTUIs` generates slash-command files but does not change the sandbox image. To install a non-npm CLI or tool (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under `sandbox.customTools` in `.agents/.airc.json`. Built-in sandbox tools (`claude-code`, `codex`, `opencode`, `gemini-cli`, `agent-infra`) keep working unchanged; `agent-infra` only provides the in-sandbox `ai` / `agent-infra` CLI and is not part of `tuis` or `customTUIs`.
+`customTUIs` generates slash-command files but does not change the sandbox image. To install a non-npm CLI or tool (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under `sandbox.customTools` in `.agents/.airc.json`. Built-in Agent Clients are installed according to `agentClients[].installInSandbox`; `agent-infra` remains a non-client entry in `sandbox.tools` and only provides the in-sandbox `ai` / `agent-infra` CLI.
 
 ### Required fields
 

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

@@ -218,37 +218,38 @@ 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`、`gemini-cli`、`opencode`）。规范化后的每个条目包含三个字段：
 
-| 取值 | 含义 |
+| 字段 | 含义 |
 |------|------|
-| `tuis` 缺失或为 `null` | 启用全部四个内建 TUI（向后兼容默认，适用于本字段引入之前的 `.airc.json`） |
-| `tuis: []` | 不维护任何内建 TUI。适用于只依赖 `customTUIs`、不需要安装任何内建命令文件的项目 |
-| `tuis: [<子集>]` | 仅维护列出的 TUI；未知 id 会被忽略 |
+| `id` | 内建 Agent Client id。规范数组为每个内建客户端保留且仅保留一个条目。 |
+| `enabled` | agent-infra 是否写入并维护该客户端的项目集成与种子命令。 |
+| `installInSandbox` | 沙箱镜像是否安装该客户端 CLI；此字段与 `enabled` 相互独立。 |
 
-`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 gemini-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 +301,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,64 @@
+import { execFileSync } from 'node:child_process';
+
+const MAX_INPUT_BYTES = 64 * 1024;
+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 || 'fresh')
+    );
+    if (event.model) args.push('--actual-model', String(event.model));
+    if (event.model_fallback_reason) args.push('--fallback-reason', String(event.model_fallback_reason));
+  } else {
+    args.push(
+      '--native-agent', String(nativeAgent),
+      '--child-id', String(event.child_id || event.agent_id || event.thread_id || '')
+    );
+  }
+  try {
+    const output = execFileSync('agent-infra-internal', args, {
+      encoding: 'utf8',
+      shell: 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/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/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.github.en.md

@@ -6,17 +6,23 @@ 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.
 
 ## 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}"
 ```
 
-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 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,23 @@
 
 ```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` 表示当前平台不支持远端发布说明能力。
 
 ## 发布 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}"
 ```
 
-命令更新既有 Release，缺失时创建；`--dry-run` 只规划操作。退出码 `0/1/2` 分别表示成功、失败和阻塞。
+命令会更新已存在的 Release，缺失时创建；`--dry-run` 只返回 planned operation。退出码为 `0` 时成功，`1` 表示稳定失败，`2` 表示网络或平台阻塞。

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 行为速查