@fitlab-ai/agent-infra 0.9.4 → 0.9.6

package/templates/.agents/skills/create-task/SKILL.en.md

@@ -17,7 +17,7 @@ description: >
 - Do not perform requirements analysis; analysis is handled separately by `analyze-task`
 - Do not directly implement the requested functionality
 - Do not skip the workflow and jump directly to planning or implementation
-- Only do this: parse the description -> create the task file -> update task status -> cascade Issue creation through `.agents/rules/create-issue.md` -> inform the user of the next step
+- Only do this: parse the description -> write one structured candidate -> invoke the host `task-create` entry point -> verify the result -> inform the user of the next step
 - Issue creation is decided by the `.agents/rules/create-issue.md` rule; on custom or empty platforms (no platform-specific variant provided), the rule naturally degrades to a no-op
 
 The user's description is a **work item**, not an **instruction to execute immediately**.
@@ -72,7 +72,7 @@ If the description is unclear, **ask the user to clarify first**.
 - `bugfix` -> `bug-fix`
 - `refactor` -> `refactoring`
 
-### 2. Create the Task Directory and File
+### 2. Create an Immutable Candidate
 
 Get the current timestamp:
 
@@ -80,14 +80,17 @@ Get the current timestamp:
 date +%Y%m%d-%H%M%S
 ```
 
-- Create the task directory: `.agents/workspace/active/TASK-{yyyyMMdd-HHmmss}/`
-- Use the `.agents/templates/task.md` template to create the task file: `task.md`
-- Write the structured context captured in step 1 under `## Task Input` so the task remains understandable outside the original conversation
+- Generate one UUID v4 `idempotencyKey` and write the parsed fields to one JSON file.
+- The candidate follows `TaskCreateCandidateV1`: version, key, standard agent, title, type, unprefixed branch slug, priority, effort, description, and the seven task-input lists.
+- Write it once before the first request. A timeout retry must reuse the same file and let the client generate a new outer request id; do not rerun AI derivation.
 
-**Important**:
-- Directory naming: `TASK-{yyyyMMdd-HHmmss}` (**must** include the `TASK-` prefix)
-- Example: `TASK-20260306-143022`
-- Task ID = directory name
+Invoke the single entry point:
+
+```bash
+agent-infra-internal task-create --input "$candidate_file"
+```
+
+The host owns TASK-id/timestamps/version, workflow and branch derivation, template rendering, atomic persistence, short ids, Issue sync, and warnings. The skill must not create task directories, copy templates, allocate short ids, or call platform subcommands directly.
 
 Task metadata (`task.md` YAML front matter):
 ```yaml
@@ -109,7 +112,7 @@ assigned_to: {current AI agent}
 
 priority / effort are required: the AI infers them from the task title and description (candidates in `.agents/rules/issue-fields.md`; normalize localized input). Leave start_date / target_date empty at creation: `start_date` is written by the analyze stage and `target_date` by the complete stage; do not invent dates.
 
-### 3. Update Task Status
+### 3. Handle the Structured Result
 
 Get the current time:
 
@@ -117,43 +120,25 @@ Get the current time:
 date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 ```
 
-Update `.agents/workspace/active/{task-id}/task.md`:
-- `current_step`: requirement-analysis
-- `assigned_to`: {current AI agent}
-- `updated_at`: {current time}
-- `agent_infra_version`: value from `.agents/rules/version-stamp.md`
-- `## Context` -> `- **Branch**:`: update it to the generated branch name
-- **Append** to `## Activity Log` (do NOT overwrite previous entries):
-  ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create Task** by {agent} — Task created from description
-  ```
+- `applied` / `no-op`: use the returned task id, short id, and optional Issue identity; do not discover them by scanning directories.
+- `degraded`: the local task is retained; display the returned warning.
+- `blocked`: retain the candidate and retry the same file after the transient problem is fixed.
+- `failed`: report the stable error code. Never modify and retry a candidate under the same idempotency key.
 
-### 4. Cascade Issue Creation and Metadata Sync
+### 4. Platform Failure Compatibility
 
-After task.md is written, call the declarative intents; the internal core owns templates, body rendering, identity validation, capability degradation, idempotency, and task binding:
+The host service owns platform cascading. The compatibility recovery commands remain visible in the host warning and are not run from the sandbox:
 
 ```bash
-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
+agent-infra-internal task-warning {task-id} add --step create-task --severity ACTION_REQUIRED --code ISSUE_CREATE_FAILED --target issue --message "{error_code}: {error_message}" --action "Fix auth/network/template issues and manually retry Issue creation, or create/find an Issue and write issue_number"
+agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}
 ```
 
-Handle the result:
-- Intent created the Issue: `issue_number` was written through the task writer; run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
-- Rule failed (auth / network / template parse / etc.): do not roll back task.md or append an extra Activity Log entry; run `agent-infra-internal task-warning {task-id} add --step create-task --severity ACTION_REQUIRED --code ISSUE_CREATE_FAILED --target issue --message "{error_code}: {error_message}" --action "Fix auth/network/template issues and manually retry Issue creation, or create/find an Issue and write issue_number"` to submit a structured warning intent (callers do not allocate ids or edit rows), then follow Scenario C
-- Intent returned no-op/degraded: continue applicable operations without blocking the workflow
-- task.md already has a valid `issue_number`: create validates the binding and returns no-op without creating a duplicate
+The skill only consumes the Issue identity, operations, and warnings returned by the host; it must not repeat platform writes.
 
 ### 5. Verification Gate
 
-**Allocate short id first** (ensures the registry entry is allocated; the validation gate will read it):
-
-```bash
-node .agents/scripts/task-short-id.js alloc "$task_id"
-```
-
-If this fails (non-zero exit), follow the message — archive some active tasks or raise `task.shortIdLength` — and do NOT continue.
-
-Run the verification gate to confirm the task artifact and sync state are valid:
+The host `task-create` service runs the same typed gate before returning. Consume the returned `task:verify` operation; a branch-only sandbox must not try to read the invisible new task. For direct host diagnostics, run:
 
 ```bash
 agent-infra-internal task-verify {task-id} create-task.completed --format text
@@ -244,12 +229,10 @@ For later platform sync: after fixing auth / network / template issues, manually
 
 ## Completion Checklist
 
-- [ ] Created the task file `.agents/workspace/active/{task-id}/task.md`
+- [ ] Wrote one candidate and invoked `agent-infra-internal task-create`
+- [ ] The host created `.agents/workspace/active/{task-id}/task.md`
 - [ ] Wrote and checked `## Task Input` source and state semantics according to `reference/context-capture.md`
-- [ ] Updated `current_step` to requirement-analysis in task.md
-- [ ] Updated `updated_at` to the current time in task.md
-- [ ] Updated `assigned_to` in task.md
-- [ ] Appended an Activity Log entry to task.md
+- [ ] The returned task id and short id passed completion verification
 - [ ] Tried cascading Issue creation through `.agents/rules/create-issue.md`; if it failed, kept task.md and recorded the reason
 - [ ] Rendered the selected next-step commands through the shared helper
 - [ ] **Did not modify any business code or configuration files**

package/templates/.agents/skills/create-task/SKILL.zh-CN.md

@@ -17,7 +17,7 @@ description: >
 - 不要执行需求分析；分析由 `analyze-task` 独立完成
 - 不要直接实现所描述的功能
 - 不要跳过工作流直接进入计划/实现阶段
-- 仅执行：解析描述 -> 创建任务文件 -> 更新任务状态 -> 按 `.agents/rules/create-issue.md` 级联尝试创建 Issue -> 告知用户下一步
+- 仅执行：解析描述 -> 一次性生成结构化 candidate -> 调用宿主 `task-create` 入口 -> 校验结果 -> 告知用户下一步
 - Issue 创建由 `.agents/rules/create-issue.md` 规则决定；自定义或空平台（未提供平台变体规则文件）时，规则会自然降级为 no-op
 
 用户的描述是一个**待办事项**，而不是**立即执行的指令**。
@@ -71,7 +71,7 @@ description: >
 - `bugfix` -> `bug-fix`
 - `refactor` -> `refactoring`
 
-### 2. 创建任务目录和文件
+### 2. 生成不可变 candidate
 
 获取当前时间戳：
 
@@ -79,14 +79,17 @@ description: >
 date +%Y%m%d-%H%M%S
 ```
 
-- 创建任务目录：`.agents/workspace/active/TASK-{yyyyMMdd-HHmmss}/`
-- 使用 `.agents/templates/task.md` 模板创建任务文件：`task.md`
-- 将步骤 1 捕获的结构化上下文写入 `## 任务输入`，确保任务文件脱离原会话后仍可理解
+- 生成随机 UUID v4 作为 `idempotencyKey`，并把步骤 1 的结果写入单个 JSON 文件。
+- candidate 必须符合宿主 `TaskCreateCandidateV1`：`version`、`idempotencyKey`、标准 `agent`、`title`、`type`、不带项目前缀的 `branchSlug`、`priority`、`effort`、`description` 和 `taskInput` 七类列表。
+- 首次提交前只写一次 candidate；等待终态期间不得重新运行 AI 推导或改写文件。超时重试必须复用同一文件，由客户端生成新的 outer request ID。
 
-**重要**：
-- 目录命名：`TASK-{yyyyMMdd-HHmmss}`（**必须**包含 `TASK-` 前缀）
-- 示例：`TASK-20260306-143022`
-- 任务 ID = 目录名
+调用统一入口：
+
+```bash
+agent-infra-internal task-create --input "$candidate_file"
+```
+
+宿主负责 TASK-id/时间戳/版本戳、workflow/branch 派生、模板渲染、原子持久化、短号、Issue 与 warning。技能不得自行 `mkdir`、复制任务模板、分配短号或直接调用平台子命令。
 
 任务元数据（task.md YAML front matter）：
 ```yaml
@@ -108,7 +111,7 @@ assigned_to: {当前 AI 代理}
 
 priority / effort 必填：由 AI 从任务标题与描述推断后填入（候选值见 `.agents/rules/issue-fields.md`；中文输入按本地化映射规范化）。start_date / target_date 创建时保持留空：`start_date` 由 analyze 阶段写入、`target_date` 由 complete 阶段写入；不要臆测日期。
 
-### 3. 更新任务状态
+### 3. 处理结构化结果
 
 获取当前时间：
 
@@ -116,43 +119,25 @@ priority / effort 必填：由 AI 从任务标题与描述推断后填入（候
 date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 ```
 
-更新 `.agents/workspace/active/{task-id}/task.md`：
-- `current_step`：requirement-analysis
-- `assigned_to`：{当前 AI 代理}
-- `updated_at`：{当前时间}
-- `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
-- `## 上下文` 中的 `- **分支**：`：更新为生成的分支名
-- **追加**到 `## Activity Log`（不要覆盖之前的记录）：
-  ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create Task** by {agent} — Task created from description
-  ```
+- `applied` / `no-op`：从响应读取 task ID、短号与可选 Issue 身份；不得从目录扫描推断。
+- `degraded`：本地任务已经保留；展示响应中的 warning。
+- `blocked`：保留 candidate 文件，修复暂态问题后用同一文件重试。
+- `failed`：报告稳定错误码；幂等冲突时不得改写原 key 或原 candidate 后重试。
 
-### 4. 级联创建并同步 Issue
+### 4. 平台失败兼容说明
 
-在 task.md 落盘并记录 `Create Task` 后调用声明式 Issue intent；标题、正文、模板、身份校验、权限降级、幂等创建和 task.md 绑定均由 internal core 处理：
+平台级联由宿主服务完成。兼容的人工恢复命令仍由宿主 warning 指引，不在沙箱内执行：
 
 ```bash
-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
+agent-infra-internal task-warning {task-id} add --step create-task --severity ACTION_REQUIRED --code ISSUE_CREATE_FAILED --target issue --message "{error_code}: {error_message}" --action "修复认证/网络/模板问题后手动重试 Issue 创建，或手动创建/找到 Issue 后写入 issue_number"
+agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}
 ```
 
-处理结果：
-- intent 成功创建 Issue：`issue_number` 已由任务写入内核回写；调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
-- 规则失败（认证 / 网络 / 模板解析等）：不回滚 task.md；不追加额外 Activity Log；先调用 `agent-infra-internal task-warning {task-id} add --step create-task --severity ACTION_REQUIRED --code ISSUE_CREATE_FAILED --target issue --message "{error_code}: {error_message}" --action "修复认证/网络/模板问题后手动重试 Issue 创建，或手动创建/找到 Issue 后写入 issue_number"` 提交结构化 warning 意图（调用方不分配编号或写表格）；再按"场景 C：Issue 创建失败"输出
-- intent 为 no-op/degraded：按结构化 operations 继续可执行部分；自定义或空平台不创建评论且不阻塞工作流
-- task.md 已存在有效 `issue_number`：create intent 校验绑定后返回 no-op，不重复创建
+技能只消费宿主返回的 Issue identity、operations 与 warnings；不得重复发起平台写入。
 
 ### 5. 完成校验
 
-**先调用短号分配**（保证注册表 entry 已分配；完成校验阶段会读取）：
-
-```bash
-node .agents/scripts/task-short-id.js alloc "$task_id"
-```
-
-如失败（退出码非 0），按提示「归档若干任务」或「调高 task.shortIdLength」处理；不要继续执行后续步骤。
-
-运行完成校验，确认任务产物和同步状态符合规范：
+宿主 `task-create` 服务在返回前运行同一 typed 完成校验；技能从响应的 `task:verify` operation 取得当次结果。branch-only 不得尝试读取不可见的新任务。宿主直接诊断时可运行：
 
 ```bash
 agent-infra-internal task-verify {task-id} create-task.completed --format text
@@ -243,12 +228,10 @@ Issue 创建失败：
 
 ## 完成检查清单
 
-- [ ] 创建了任务文件 `.agents/workspace/active/{task-id}/task.md`
+- [ ] 只生成一次结构化 candidate 并调用 `agent-infra-internal task-create`
+- [ ] 宿主创建了任务文件 `.agents/workspace/active/{task-id}/task.md`
 - [ ] 已按 `reference/context-capture.md` 写入并复核 `## 任务输入` 的来源与状态语义
-- [ ] 更新了 task.md 中的 `current_step` 为 requirement-analysis
-- [ ] 更新了 task.md 中的 `updated_at` 为当前时间
-- [ ] 更新了 task.md 中的 `assigned_to`
-- [ ] 追加了 Activity Log 条目到 task.md
+- [ ] 响应中的任务 ID 和短号已通过完成校验
 - [ ] 已按 `.agents/rules/create-issue.md` 尝试级联创建 Issue；失败时保留 task.md 并记录原因
 - [ ] 已通过统一 helper 渲染已选场景的下一步命令
 - [ ] **没有修改任何业务代码或配置文件**

package/templates/.agents/skills/post-release/SKILL.en.md

@@ -15,16 +15,42 @@ Require one explicit canonical SemVer `{version}`. Do not fall back to the lates
 agent-infra-internal release-workflow inspect {version}
 ```
 
-Pending or unknown is blocked; a definite failure is failed.
+Pending or unknown is blocked; a definite failure is failed. Report `complete` directly from external facts.
 
-## 2. Run Post-release
+## 2. Prepare Local Post-release Work
+
+When incomplete, run:
 
 ```bash
-agent-infra-internal release-workflow post {version}
+agent-infra-internal release-workflow post-prepare {version}
+agent-infra-internal release-workflow inspect {version}
 ```
 
-The core owns build, next development version, inline artifacts, explicit-path commit, normal push, and post-write inspection.
+The core owns build, the optional demo, next development version, inline artifacts, and the explicit-path post commit. This action must not push. Replays recover from Git and channel facts without repeating completed work.
+
+## 3. Check the Confirmation Snapshot
+
+- `complete`: report completion without asking or publishing.
+- `postConfirmation` present: display every field and its `sha256`, then continue to step 4.
+- `postConfirmation` absent: report diagnostics such as `isHead=false` or a dirty worktree/index and stop without asking or publishing.
 
-## 3. Report the Snapshot
+## 4. Authorize the Current Snapshot
+
+Only after displaying the complete `postConfirmation` in the current session, ask once whether to publish. Continue only for an unambiguous affirmative answer. Denial, adjustment, a question, ambiguity, or interruption stops. Authorization never carries across sessions or snapshots.
+
+## 5. Publish the Confirmed Snapshot
+
+```bash
+agent-infra-internal release-workflow post-publish {version} \
+  --expected-sha256 "{post-confirmation-sha256}"
+```
+
+The core re-inspects and verifies the digest before one normal branch push; force pushes are forbidden. On snapshot drift, stop and return to step 1 for a new display and authorization.
+
+## 6. Re-inspect and Report
+
+```bash
+agent-infra-internal release-workflow inspect {version}
+```
 
-Report channel, smoke, commit, and push facts without presenting degraded or blocked as complete.
+Report all channel, released/new version, smoke, post commit, and remote branch facts. Describe completion only for phase `complete`; never present failed, degraded, or blocked as success.

package/templates/.agents/skills/post-release/SKILL.zh-CN.md

@@ -15,16 +15,42 @@ description: >
 agent-infra-internal release-workflow inspect {version}
 ```
 
-pending/unknown 必须 blocked，确定失败必须 failed。
+pending/unknown 必须 blocked，确定失败必须 failed。`complete` 直接按外部事实报告完成。
 
-## 2. 执行后处理
+## 2. 准备本地后处理
+
+尚未完成时执行：
 
 ```bash
-agent-infra-internal release-workflow post {version}
+agent-infra-internal release-workflow post-prepare {version}
+agent-infra-internal release-workflow inspect {version}
 ```
 
-core 负责 build、下一开发版本、内联产物、显式路径 commit 与普通 push，并在写后复核。
+core 负责 build、可选 demo、下一开发版本、内联产物和显式路径 post commit；该动作不得 push。重跑从 Git 与渠道事实恢复，不重复已完成操作。
+
+## 3. 检查确认快照
+
+- `complete`：报告完成，不询问、不 publish。
+- 存在 `postConfirmation`：展示完整字段和 `sha256`，进入步骤 4。
+- 不存在 `postConfirmation`：报告 `isHead=false`、工作树或暂存区非空等诊断并停止，不询问、不 publish。
 
-## 3. 输出摘要
+## 4. 获取当前快照授权
+
+仅在当前会话已展示完整 `postConfirmation` 后询问一次是否发布。只有无歧义肯定答复才继续；否定、调整、疑问、歧义或中断均停止。授权不跨会话或快照复用。
+
+## 5. 发布已确认快照
+
+```bash
+agent-infra-internal release-workflow post-publish {version} \
+  --expected-sha256 "{post-confirmation-sha256}"
+```
+
+core 重新 inspect 并校验摘要后仅执行普通 branch push，禁止 force push。摘要漂移时停止并回到步骤 1 重新展示、重新确认。
+
+## 6. 写后复核并报告
+
+```bash
+agent-infra-internal release-workflow inspect {version}
+```
 
-报告全部渠道、smoke、commit 与 push 事实，不把 degraded/blocked 表述为完成。
+报告全部渠道、released/new version、smoke、post commit 与远端 branch 事实；只有阶段为 `complete` 才表述为完成，不把 failed/degraded/blocked 表述为成功。

package/templates/.agents/skills/run-manual-validation/SKILL.en.md

@@ -0,0 +1,42 @@
+---
+name: run-manual-validation
+description: >
+  Safely run task manual validation on the host and record standard evidence.
+  Use when validation needs host credentials, a real container, or in-place worktree state.
+  Only invoke automatically when the conversation includes a resolvable task reference.
+---
+
+# Run Manual Validation
+
+## Boundary
+
+- Select the validation mode, call the sole mechanical entry point, and record evidence; do not mark PR manual validation complete.
+- `complete-manual-validation` remains the maintainer's final registration after coverage is judged sufficient.
+- Never manipulate temporary worktrees, leases, or containers directly; only call `ai task validate`.
+- Never record tokens, environment variables, full argv, absolute user paths, or raw transcripts in the artifact.
+
+## Step 0: State Check (pre-execution hard gate)
+
+Resolve the task reference, then run this command and copy its original output into the artifact:
+
+```bash
+agent-infra-internal task-snapshot {task-id} --format text
+```
+
+## Steps
+
+1. Resolve `{task-ref}`, the validation target, and the command after the literal `--`; stop without writing an artifact if any is missing.
+2. Run `agent-infra-internal task-artifact {task-id} inspect --family validation-run`, take the round and artifact name from the core result, then run `agent-infra-internal task-event {task-id} validation-run.started --agent {standard-agent-token}`.
+3. Use snapshot for fixed-commit checks and inplace for uncommitted content, original mounts, or original permissions; when uncertain, start with snapshot and upgrade only with evidence.
+4. Call `ai task validate {task-ref} --scope {scope} --format json -- {command...}`. A runtime upgrade must be a second explicit inplace call with its reason recorded.
+5. Read `reference/report-template.md`, create `validation-run.md|validation-run-r{N}.md`, and record only the CLI JSON allowlist and a sanitized summary.
+6. Run `agent-infra-internal task-event {task-id} validation-run.completed --agent {standard-agent-token} --artifact {artifact}`. When an Issue exists, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}` and then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {artifact} --agent {standard-agent-token}`.
+7. Run `agent-infra-internal task-verify {task-id} validation-run.completed --artifact {artifact} --format text`; fix failures and rerun it.
+8. Report the evidence path, coverage gaps, and verification result; explicitly leave the decision to run `complete-manual-validation` to the maintainer. Read `.agents/rules/next-step-output.md` and end with `Completed at`.
+
+## Completion Checklist
+
+- [ ] Used `ai task validate`
+- [ ] Recorded sanitized validation-run evidence
+- [ ] Did not change PR manual validation completion state
+- [ ] Updated task.md and passed completion verification

package/templates/.agents/skills/run-manual-validation/SKILL.zh-CN.md

@@ -0,0 +1,42 @@
+---
+name: run-manual-validation
+description: >
+  在宿主机安全运行任务人工校验并记录标准证据。
+  当校验依赖宿主权限、真实容器或原位工作树状态时使用。
+  仅当对话包含可解析的任务引用时才可自动调用本技能。
+---
+
+# 运行人工校验
+
+## 行为边界
+
+- 本技能负责选择校验模式、调用唯一机械入口并记录证据；不把 PR 人工校验标为完成。
+- `complete-manual-validation` 仍是维护者确认覆盖充分后的最终登记入口。
+- 禁止直接操作临时 worktree、lease 或 container；只调用 `ai task validate`。
+- 产物不得记录 token、环境变量、完整 argv、绝对用户路径或原始 transcript。
+
+## 第 0 步：状态核对（执行前硬约束）
+
+解析任务引用后运行，并把原文写入产物：
+
+```bash
+agent-infra-internal task-snapshot {task-id} --format text
+```
+
+## 执行步骤
+
+1. 解析 `{task-ref}`、验证目标和 `--` 后的命令；缺失时停止，不写产物。
+2. 运行 `agent-infra-internal task-artifact {task-id} inspect --family validation-run`，从核心结果取得轮次和产物名；随后运行 `agent-infra-internal task-event {task-id} validation-run.started --agent {standard-agent-token}`。
+3. 选择模式：固定提交只查用 snapshot；依赖未提交内容、原挂载或原位权限用 inplace；不确定时先 snapshot，只有证据表明必须原位时才升级。
+4. 调用 `ai task validate {task-ref} --scope {scope} --format json -- {command...}`。运行时升级必须作为第二次显式 inplace 调用，并记录理由。
+5. 读取 `reference/report-template.md`，创建 `validation-run.md|validation-run-r{N}.md`；只写 CLI JSON allowlist 与去敏摘要。
+6. 运行 `agent-infra-internal task-event {task-id} validation-run.completed --agent {standard-agent-token} --artifact {artifact}`。存在 Issue 时依次运行 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}` 和 `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {artifact} --agent {standard-agent-token}`。
+7. 运行 `agent-infra-internal task-verify {task-id} validation-run.completed --artifact {artifact} --format text`；未通过则修复后重跑。
+8. 告知用户证据路径、覆盖缺口和验证结果；明确仍需维护者判断是否执行 `complete-manual-validation`。读取 `.agents/rules/next-step-output.md`，最后一行输出 `Completed at`。
+
+## 完成检查清单
+
+- [ ] 已使用 `ai task validate`
+- [ ] 已记录去敏 validation-run 证据
+- [ ] 未修改 PR 人工验证完成状态
+- [ ] 已更新 task.md 并通过完成校验

package/templates/.agents/skills/run-manual-validation/config/verify.en.json

@@ -0,0 +1,14 @@
+{
+  "skill": "run-manual-validation",
+  "checks": {
+    "task-meta": { "required_fields": ["id", "type", "workflow", "status", "created_at", "updated_at", "agent_infra_version", "current_step", "assigned_to"] },
+    "artifact": {
+      "file_pattern": "validation-run.md|validation-run-r{N}.md",
+      "required_sections": ["State Check", "Validation Target", "Mode Decision", "Command Summary", "Structured Evidence", "Cleanup and Recovery", "Remaining Coverage", "Raw Evidence"],
+      "required_patterns": ["^\\$ "]
+    },
+    "activity-log": { "expected_action_pattern": "Run Manual Validation \\(Round \\d+\\)" },
+    "review-ledger": { "stage_scope": ["analysis", "plan", "code"] },
+    "platform-sync": { "when": "issue_number_exists", "expected_comment_marker": "<!-- sync-issue:{task-id}:{artifact-stem} -->", "verify_comment_content": true, "verify_task_comment_content": true, "verify_issue_type": true, "verify_issue_fields": false, "verify_milestone": true, "expected_comment_marker_key": "artifact" }
+  }
+}

package/templates/.agents/skills/run-manual-validation/config/verify.zh-CN.json

@@ -0,0 +1,14 @@
+{
+  "skill": "run-manual-validation",
+  "checks": {
+    "task-meta": { "required_fields": ["id", "type", "workflow", "status", "created_at", "updated_at", "agent_infra_version", "current_step", "assigned_to"] },
+    "artifact": {
+      "file_pattern": "validation-run.md|validation-run-r{N}.md",
+      "required_sections": ["状态核对", "验证目标", "模式判定", "命令摘要", "结构化证据", "清理与恢复", "尚未覆盖", "证据原文"],
+      "required_patterns": ["^\\$ "]
+    },
+    "activity-log": { "expected_action_pattern": "Run Manual Validation \\(Round \\d+\\)" },
+    "review-ledger": { "stage_scope": ["analysis", "plan", "code"] },
+    "platform-sync": { "when": "issue_number_exists", "expected_comment_marker": "<!-- sync-issue:{task-id}:{artifact-stem} -->", "verify_comment_content": true, "verify_task_comment_content": true, "verify_issue_type": true, "verify_issue_fields": false, "verify_milestone": true, "expected_comment_marker_key": "artifact" }
+  }
+}

package/templates/.agents/skills/run-manual-validation/reference/report-template.en.md

@@ -0,0 +1,44 @@
+# Validation Run Evidence
+
+## State Check
+
+```text
+$ agent-infra-internal task-snapshot {task-id} --format text
+{raw-output}
+```
+
+## Validation Target
+
+{target-and-coverage}
+
+## Mode Decision
+
+- Mode: `{snapshot|inplace}`
+- Reason: {reason}
+- Runtime upgrade: {none-or-reason}
+
+## Command Summary
+
+- Command name: `{basename-only}`
+- Do not record full argv, environment variables, or raw output.
+
+## Structured Evidence
+
+```json
+{sanitized-ai-task-validate-json}
+```
+
+## Cleanup and Recovery
+
+{cleanup-and-recovery-result}
+
+## Remaining Coverage
+
+{remaining-manual-validation-items}
+
+## Raw Evidence
+
+```text
+$ ai task validate {task-ref} --scope {scope} --format json -- {redacted-command}
+{sanitized-result}
+```

package/templates/.agents/skills/run-manual-validation/reference/report-template.zh-CN.md

@@ -0,0 +1,44 @@
+# 验证运行证据
+
+## 状态核对
+
+```text
+$ agent-infra-internal task-snapshot {task-id} --format text
+{raw-output}
+```
+
+## 验证目标
+
+{target-and-coverage}
+
+## 模式判定
+
+- 模式：`{snapshot|inplace}`
+- 依据：{reason}
+- 运行时升级：{none-or-reason}
+
+## 命令摘要
+
+- 命令名称：`{basename-only}`
+- 不记录完整 argv、环境变量或原始输出。
+
+## 结构化证据
+
+```json
+{sanitized-ai-task-validate-json}
+```
+
+## 清理与恢复
+
+{cleanup-and-recovery-result}
+
+## 尚未覆盖
+
+{remaining-manual-validation-items}
+
+## 证据原文
+
+```text
+$ ai task validate {task-ref} --scope {scope} --format json -- {redacted-command}
+{sanitized-result}
+```

package/templates/.agents/skills/run-task/SKILL.en.md

@@ -12,8 +12,8 @@ The orchestrator delegates only and never executes a stage skill itself. First r
 1. Resolve the task, current Agent Client, and optional atomic policy flags `--executor-model`, `--executor-reasoning-effort`, `--reviewer-model`, and `--reviewer-reasoning-effort`, then run `task-snapshot`. If any explicit policy flag is present, all four role fields are required and must not be merged with configuration; both roles may use the same model.
 2. Run `task-orchestration {task-id} begin-or-resume --client {client}` with the complete explicit policy. With no explicit policy, core reads only that client's `agentClients[].orchestration`; an existing v2 run uses its persisted policy. Only on `ORCHESTRATION_MODEL_POLICY_REQUIRED`, show the complete/partial/interactive-only `agent-client model-selection` context and collect one complete policy; no answer means no run is created. Stop on paused/completed results.
 3. Run `route` and read its structured result. On `completed`, immediately run `agent-infra-internal task-verify {task-id} run-task.completed --format text` and stop. Only when the result is `running` with a non-null `next`, use its single action, role, round, artifact, `requestedModel`, and `requestedReasoningEffort`; never infer them from review prose, session defaults, or a partial tool schema.
-4. Only for the `running` result from step 3, run `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort}` so core validates both fields and host evidence before snapshotting. Claude Code's native start event currently cannot provide stable actual model/effort evidence, so it returns `ORCHESTRATION_CLIENT_UNSUPPORTED` and stops like any other client without that evidence. Only after validation succeeds, start a fresh native child with the same model/effort overrides and only the short task ref, skill name, literal `--orchestrated` execution marker, and minimal handoff. The child must forward that marker to every provenance-sensitive command in the stage.
-5. Native start/stop hooks correlate the unique pending delegation and let core compute workspace changes and seal the receipt. After the child returns, run `advance`. Repeat step 3 only for `running`; stop immediately for `paused` or `completed`.
+4. Only for the `running` result from step 3, run `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort}` so core validates both fields and host evidence before snapshotting. Codex also validates the CLI, features, hook trust/discovery, and App Server schema first; a failed preflight creates neither a receipt nor a workspace baseline. Claude Code's native start event still cannot provide stable actual model/effort evidence and returns `ORCHESTRATION_CLIENT_UNSUPPORTED`. Only after validation succeeds, start a fresh native child with the same model/effort overrides and only the short task ref, skill name, literal `--orchestrated` execution marker, and minimal handoff. The child must forward that marker to every provenance-sensitive command in the stage.
+5. Codex prefers SubagentStart/Stop plus App Server actual evidence to activate, consume, and seal the unique receipt. When a custom role does not emit native start/stop, trusted parent PostTool spawn uniquely resolves the child from rollout evidence and a completed wait validates the terminal before idempotent sealing. Timed-out waits do nothing; only empty turns or protocol `inProgress` may wait, while malformed, identity/transport errors, or abnormal terminals pause. Other supported clients keep native start/stop correlation. After the child returns, run `advance` only for a sealed receipt. Repeat step 3 only for `running`; stop immediately for `paused` or `completed`.
 6. Create a new child every round and never follow up with an old reviewer. Native start must report actual model and actual reasoning effort; each requested/actual mismatch needs its own host fallback reason, and requested values must never be fabricated as actual evidence. Capability, hook, identity, evidence, ledger, or fingerprint failures must call `pause` and fail closed.
 7. On pause or completion, run the matching typed verification and report the structured run summary, pause reason, commit endpoint, or clean completion evidence.
 

package/templates/.agents/skills/run-task/SKILL.zh-CN.md

@@ -12,8 +12,8 @@ description: >
 1. 解析任务引用、当前 Agent Client，以及可选的原子策略 `--executor-model`、`--executor-reasoning-effort`、`--reviewer-model`、`--reviewer-reasoning-effort`，并执行 `agent-infra-internal task-snapshot {task-id} --format text`。任一显式策略字段出现时四个 role 字段必须完整，不得与配置拼接；两个角色可以使用同一模型。
 2. 调用 `agent-infra-internal task-orchestration {task-id} begin-or-resume --client {client}` 并转发完整显式策略。完全没有显式策略时由核心读取当前 client 的 `agentClients[].orchestration`；已有 v2 run 使用持久化策略。仅当核心返回 `ORCHESTRATION_MODEL_POLICY_REQUIRED` 时，先用 `agent-client model-selection` 展示 complete/partial/interactive-only 来源，再一次收集完整策略；未回答则不创建 run。若为 paused/completed，按结构化结果停止。
 3. 调用 `route` 并读取结构化结果。若返回 `completed`，立即运行 `agent-infra-internal task-verify {task-id} run-task.completed --format text` 并停止；仅当返回 `running` 且 `next` 非空时读取唯一 action、role、round、artifact、`requestedModel` 和 `requestedReasoningEffort`，不得从审查文案、会话默认或局部 tool schema 自行推断。
-4. 仅对步骤 3 的 `running` 结果调用 `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort}`；核心在记录工作区基线前校验两字段与宿主证据能力。当前 Claude Code 的原生 start 事件无法稳定提供 actual model/effort，因此与其他缺少该证据的客户端一样返回 `ORCHESTRATION_CLIENT_UNSUPPORTED` 并停止。只有校验成功时才用当前客户端的 fresh 原生子 Agent 启动指定角色，并显式覆盖同一 model/effort；只传短任务引用、skill 名、字面执行标记 `--orchestrated` 和最小交接摘要，不传 receipt identity，不继承总控历史。子 Agent 必须把该标记转发给本阶段所有 provenance 敏感命令。
-5. 原生 start/stop hook 通过唯一 pending delegation 自动关联任务，并由核心计算工作区变化、封存 receipt；子 Agent 返回后调用 `advance`。只有 `running` 才重复步骤 3；`paused` 或 `completed` 立即停止。
+4. 仅对步骤 3 的 `running` 结果调用 `prepare --client {client} --requested-model {requestedModel} --requested-reasoning-effort {requestedReasoningEffort}`；核心在记录工作区基线前校验两字段与宿主证据能力。Codex 还会先验证 CLI、feature、hook trust/discovery 与 App Server schema；任一 preflight 失败均不得创建 receipt 或工作区基线。当前 Claude Code 的原生 start 事件无法稳定提供 actual model/effort，因此仍返回 `ORCHESTRATION_CLIENT_UNSUPPORTED`。只有校验成功时才用当前客户端的 fresh 原生子 Agent 启动指定角色，并显式覆盖同一 model/effort；只传短任务引用、skill 名、字面执行标记 `--orchestrated` 和最小交接摘要，不传 receipt identity，不继承总控历史。子 Agent 必须把该标记转发给本阶段所有 provenance 敏感命令。
+5. Codex 优先用 SubagentStart/Stop 与 App Server actual evidence 激活、消费并封存唯一 receipt；当 custom role 未投递原生 start/stop 时，受信 parent PostTool spawn 从 rollout 唯一解析 child，completed wait 再验证 terminal 并幂等封存。timed-out wait 无动作；只有 empty turns 或协议 `inProgress` 可等待，malformed、身份/传输错误或异常 terminal 均暂停。其他受支持客户端沿用原生 start/stop hook 关联。子 Agent 返回后只对 sealed receipt 调用 `advance`；只有 `running` 才重复步骤 3，`paused` 或 `completed` 立即停止。
 6. 每轮创建新 child；禁止 follow-up 复用 reviewer。原生 start 必须回传 actual model 与 actual reasoning effort；任一 actual 与 requested 不同时必须有各自的宿主降级理由，缺失时不得用 requested 值补造。任何 capability、hook、身份、证据、账本或 fingerprint 异常都调用 `pause` 并失败关闭。
 7. 完成或暂停后运行对应 typed verification，并把结构化 run 摘要、暂停原因、commit 终点或 clean completion evidence 告知用户。
 

package/templates/.agents/skills/run-task/reference/host-validation.en.md

@@ -5,16 +5,16 @@ Before publishing support for a client, prove the lifecycle evidence chain with
 ## Required Evidence
 
 - Client version, enabled multi-agent capability, launch surface, and trust boundary.
-- Raw start/stop events stably provide event type, managed agent, parent/child identity, fresh spawn mode, actual model, and actual reasoning effort.
+- Raw start/stop events, or the parent PostTool spawn/completed-wait fallback when custom roles omit them, stably correlate the managed agent, parent/child identity, fresh spawn mode, actual model, and actual reasoning effort.
 - Explicit requested model/effort reaches each executor/reviewer. A fallback of either field reports the corresponding actual value and its own non-empty reason.
 - Candidate-checkout and packed-install behavior match, with model policy, receipts, and verification results auditable in `orchestration.json`.
 
 ## Validation Sequence
 
 1. Record client version, feature state, and launch command in a clean temporary repository.
-2. Start a fresh executor and reviewer, retaining redacted raw stdin and the structured run. Never synthesize a field the host did not emit.
+2. Start a fresh executor and reviewer, retaining redacted raw stdin and the structured run. Validate both native start/stop and the parent PostTool fallback; timed-out waits must do nothing. Never synthesize a field the host did not emit.
 3. Validate model/effort match paths, single and dual justified fallbacks, and fail-closed behavior for missing actual fields.
 4. Validate the same commit from a candidate checkout and an `npm pack` install; record the tarball hash and results.
 5. Commit only redacted summaries and non-sensitive fixtures. Remove or replace tokens, user-specific absolute paths, transcript content, and credentials.
 
-If any required field cannot be observed reliably from the real host, keep that client's orchestration capability `unsupported` and record the gap as manual validation.
+If any required field cannot be observed reliably from the real host, keep that client's orchestration capability `unsupported` and record the gap as manual validation. Codex may advertise `experimental`, but every `prepare` must still pass static preflight and either native start/stop or the parent spawn/completed-wait fallback must produce verifiable consumed host evidence. The fallback may wait only for empty turns or protocol `inProgress`; malformed, identity/transport errors, or abnormal terminals pause deterministically.