@fitlab-ai/agent-infra 0.9.15 → 0.11.0

package/templates/.agents/skills/complete-task/reference/external-delivery.en.md

@@ -4,7 +4,7 @@ This scenario applies only to an active task whose completion canonical inventor
 
 ## Typed State Machine
 
-Run `agent-infra-internal platform-pr resolve-external {task-id} --agent {agent} [--pr {N}]`. Core checks the completion inventory first. A non-empty inventory returns `mode=normal`, and supplying `--pr` then fails. An empty inventory requires a positive `issue_number`; otherwise core returns `EXTERNAL_DELIVERY_ISSUE_REQUIRED`.
+Run `agent-infra-internal platform-pr resolve-external {task-id} --agent {agent} [--pr {N}]`. Core checks the completion inventory first. A non-empty inventory returns `mode=normal`, and supplying `--pr` then fails. An empty inventory requires a valid `platform_issue_identity`; otherwise core returns `EXTERNAL_DELIVERY_ISSUE_REQUIRED`.
 
 The platform adapter supplies authoritative Issue closing change requests across all pages. Only candidates with a matching base repository, complete identity, and merge evidence are eligible. One candidate is selected automatically; ambiguity, conflicts, and missing evidence fail closed. `--pr` may only select an authoritative eligible closing candidate and cannot bypass repository, Issue, merge, or identity validation.
 

package/templates/.agents/skills/complete-task/reference/external-delivery.zh-CN.md

@@ -4,7 +4,7 @@
 
 ## Typed 状态机
 
-调用 `agent-infra-internal platform-pr resolve-external {task-id} --agent {agent} [--pr {N}]`。core 先检查 completion inventory；非空时返回 `mode=normal`，且显式 `--pr` 会失败。空 inventory 必须有正整数 `issue_number`，否则返回 `EXTERNAL_DELIVERY_ISSUE_REQUIRED`。
+调用 `agent-infra-internal platform-pr resolve-external {task-id} --agent {agent} [--pr {N}]`。core 先检查 completion inventory；非空时返回 `mode=normal`，且显式 `--pr` 会失败。空 inventory 必须有有效 `platform_issue_identity`，否则返回 `EXTERNAL_DELIVERY_ISSUE_REQUIRED`。
 
 core 通过平台 adapter 读取 Issue 的权威 closing change requests，穷尽分页后只把 base 仓库匹配任务仓库且已经合并、身份字段完整的候选视为 eligible。唯一候选自动选择；多候选、身份冲突或证据缺失均 fail closed。`--pr` 只能从权威 closing eligible 集合中显式选择，不能绕过仓库、Issue、合并或身份校验。
 

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

@@ -47,7 +47,7 @@ No Pull Request is required; run instead:
 
 Parse the task scope first: an optional `--task <ref>` or `-t <ref>` selects `{task-id}`; a positional task ref is not interpreted. The remaining positional argument, when present, is `{target-branch}`.
 
-If `{task-id}` is provided, read `.agents/workspace/active/{task-id}/task.md` to load task metadata such as `issue_number` and `type`.
+If `{task-id}` is provided, read `.agents/workspace/active/{task-id}/task.md` to load task metadata such as `platform_issue_identity` and `type`.
 If `{task-id}` is omitted, try to resolve it from the current session context; if it still cannot be determined, skip task-association logic in later steps.
 
 ### 2. Determine the Target Branch
@@ -70,7 +70,7 @@ Run `agent-infra-internal task-delivery {task-id} deliver --agent {standard-agen
 
 Read `.agents/rules/issue-pr-commands.md`, write the title and body to temporary files, then invoke its `platform-pr create` intent. Under the task lock, core uses remote branch and exact head/base/PR identity facts: one existing PR is reused and bound, zero creates, and multiple matches fail deterministically. Review artifacts and task sync records are not create-pr prerequisites, and replays must not create duplicate PRs.
 
-If `{task-id}` is available and the related task provides `issue_number`, keep `Closes #{issue-number}` in the PR body.
+If `{task-id}` is available and the related task provides `platform_issue_identity`, keep `Closes #{issue-number}` or the provider-equivalent closing keyword in the PR body when supported.
 
 ### 6. Sync PR Metadata
 

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

@@ -47,7 +47,7 @@ description: >
 
 先解析 task scope：可选的 `--task <ref>` 或 `-t <ref>` 绑定 `{task-id}`；位置 task ref 不再解释。剩余的可选位置参数绑定为 `{target-branch}`。
 
-如果提供了 `{task-id}`，读取 `.agents/workspace/active/{task-id}/task.md` 获取任务信息（例如 `issue_number`、`type` 等）。
+如果提供了 `{task-id}`，读取 `.agents/workspace/active/{task-id}/task.md` 获取任务信息（例如 `platform_issue_identity`、`type` 等）。
 如果未提供，可从当前 session 上下文获取；仍无法确定 `{task-id}` 时，后续步骤中的任务关联逻辑跳过。
 
 ### 2. 确定目标分支
@@ -70,7 +70,7 @@ description: >
 
 执行前先读取 `.agents/rules/issue-pr-commands.md`，把标题和正文写入临时文件，并调用其中的 `platform-pr create` intent。core 在任务锁内按 remote branch、head/base 和 PR 身份事实执行：唯一既有 PR 会复用并绑定，零个才创建，多个稳定失败；review 或 task sync 记录不作为创建 PR 的前置门禁，重放不得产生重复 PR。
 
-如果获取到 `{task-id}` 且对应任务提供了 `issue_number`，必须在 PR 正文中保留 `Closes #{issue-number}`。
+如果获取到 `{task-id}` 且对应任务提供了 `platform_issue_identity`，在 provider 支持 numeric closing reference 时必须在 PR 正文中保留 `Closes #{issue-number}` 或 provider 等价关闭关键字。
 
 ### 6. 同步 PR 元数据
 

package/templates/.agents/skills/create-pr/config/verify.json

@@ -18,7 +18,7 @@
       "expected_action_pattern": "(Create PR|PR Created)"
     },
     "platform-sync": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "expected_pr_comment_marker": "<!-- sync-pr:{task-id}:summary -->",
       "verify_in_labels_match_pr": true,
       "verify_in_labels_computed": true,

package/templates/.agents/skills/create-pr/reference/pr-body-template.en.md

@@ -55,8 +55,8 @@ Milestone rule:
 
 ## Create the PR
 
-- Extract `issue_number` from task.md when this work belongs to an active task
-- If `issue_number` exists, complete the prerequisite code-hosting platform detection steps first, then query the Issue via `.agents/rules/issue-pr-commands.md`
+- Extract `platform_issue_identity` from task.md when this work belongs to an active task
+- If `platform_issue_identity` exists, complete the prerequisite code-hosting platform detection steps first, then query the Issue via `.agents/rules/issue-pr-commands.md`
 - Before calling the PR creation command, check whether the current branch already has a PR. If it does, report the PR URL and state, then stop without repeating metadata sync or summary publication
 - Use HEREDOC to pass the PR body
 - Replace `{$IssueNumber}` in the template when present

package/templates/.agents/skills/create-pr/reference/pr-body-template.zh-CN.md

@@ -55,8 +55,8 @@ Milestone 规则：
 
 ## 创建 PR
 
-- 当前工作属于 active task 时，从 task.md 提取 `issue_number`
-- 如果存在 `issue_number`，先完成代码托管平台检测，再通过 `.agents/rules/issue-pr-commands.md` 查询 Issue
+- 当前工作属于 active task 时，从 task.md 提取 `platform_issue_identity`
+- 如果存在 `platform_issue_identity`，先完成代码托管平台检测，再通过 `.agents/rules/issue-pr-commands.md` 查询 Issue
 - 调用 PR 创建命令前，先检查当前分支是否已有 PR；若已有，报告 PR URL 和状态后停止，不重复执行元数据同步或 summary 发布
 - 使用 HEREDOC 传入 PR 正文
 - 模板中存在 `{$IssueNumber}` 时进行替换

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

@@ -139,7 +139,7 @@ automatically. Recover with the original request or inspect host task state firs
 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 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 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 run platform-issue bind"
 agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}
 ```
 
@@ -177,7 +177,7 @@ Task information:
 - Title: {title}
 - Type: {type}
 - Workflow: {workflow}
-- Issue: #{issue_number} {issue_url}
+- Issue: #{issue-number} {issue_url}
 
 Output file:
 - Task file: .agents/workspace/active/{task-id}/task.md
@@ -228,10 +228,10 @@ Output file:
 Next step - run requirements analysis:
 {next-step-commands}
 
-For later platform sync: after fixing auth / network / template issues, manually run the Issue creation flow in `.agents/rules/create-issue.md` for this task; or manually create/find an Issue and write `issue_number` into task.md so later skills can take over cascade sync.
+For later platform sync: after fixing auth / network / template issues, manually run the Issue creation flow in `.agents/rules/create-issue.md` for this task; or manually create/find an Issue and run `platform-issue bind`, which resolves the token through the provider and writes `platform_issue_identity` so later skills can take over cascade sync.
 
 [ACTION REQUIRED] Workflow warnings are open:
-  - WW-N ISSUE_CREATE_FAILED (issue): Fix auth/network/template issues and manually retry Issue creation, or create/find an Issue and write issue_number
+  - WW-N ISSUE_CREATE_FAILED (issue): Fix auth/network/template issues and manually retry Issue creation, or create/find an Issue and run `platform-issue bind`
 ```
 
 
@@ -256,7 +256,7 @@ Wait for the user to run the `analyze-task` skill.
 1. **Clarity**: if the user description is vague or missing key information, ask for clarification first
 2. **Difference from `import-issue`**: `import-issue` imports from an Issue; `create-task` creates from a free-form description
 3. **Workflow order**: after creating a task, typically run `analyze-task` before `plan-task`
-4. **Issue cascade failure**: if the rule fails, task.md remains; when platform sync is needed later, manually write `issue_number` and continue the workflow
+4. **Issue cascade failure**: if the rule fails, task.md remains; when platform sync is needed later, run `platform-issue bind` and do not hand-write the legacy Issue field
 
 ## Error Handling
 

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

@@ -137,7 +137,7 @@ candidate 和新的 outer request ID 重试；`recovery: same-request-id` 或
 平台级联由宿主服务完成。兼容的人工恢复命令仍由宿主 warning 指引，不在沙箱内执行：
 
 ```bash
-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 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 后执行 platform-issue bind"
 agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}
 ```
 
@@ -175,7 +175,7 @@ agent-infra-internal task-verify {task-id} create-task.completed --format text
 - 标题：{title}
 - 类型：{type}
 - 工作流：{workflow}
-- Issue：#{issue_number} {issue_url}
+- Issue：#{issue-number} {issue_url}
 
 产出文件：
 - 任务文件：.agents/workspace/active/{task-id}/task.md
@@ -226,10 +226,10 @@ Issue 创建失败：
 下一步 - 执行需求分析：
 {next-step-commands}
 
-后续如需平台同步：修复认证/网络/模板问题后，可按 `.agents/rules/create-issue.md` 对当前任务手动执行一次 Issue 创建；或手动创建/查找 Issue，并把 `issue_number` 写入 task.md，后续技能会接管级联同步。
+后续如需平台同步：修复认证/网络/模板问题后，可按 `.agents/rules/create-issue.md` 对当前任务手动执行一次 Issue 创建；或手动创建/查找 Issue 后执行 `platform-issue bind`，由 provider 解析 token 并写入 `platform_issue_identity`，后续技能会接管级联同步。
 
 [ACTION REQUIRED] Workflow warnings are open:
-  - WW-N ISSUE_CREATE_FAILED (issue): 修复认证/网络/模板问题后手动重试 Issue 创建，或手动创建/找到 Issue 后写入 issue_number
+  - WW-N ISSUE_CREATE_FAILED (issue): 修复认证/网络/模板问题后手动重试 Issue 创建，或手动创建/找到 Issue 后执行 `platform-issue bind`
 ```
 
 
@@ -254,7 +254,7 @@ Issue 创建失败：
 1. **清晰度**：如果用户描述模糊或缺少关键信息，先要求澄清
 2. **与 import-issue 的区别**：`import-issue` 从 Issue 导入任务；`create-task` 从自由描述创建
 3. **工作流顺序**：创建任务后，通常先执行 `analyze-task` 再进入 `plan-task`
-4. **Issue 级联失败**：如果规则执行失败，task.md 仍保留；需要后续平台同步时，可手动写入 `issue_number` 后继续执行工作流
+4. **Issue 级联失败**：如果规则执行失败，task.md 仍保留；需要后续平台同步时，可手动执行 `platform-issue bind`，不得手工写入旧的 Issue 字段
 
 ## 错误处理
 

package/templates/.agents/skills/create-task/config/verify.json

@@ -21,7 +21,7 @@
       "expected_action_pattern": "(Create Task|Task Created)"
     },
     "platform-sync": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "issue_must_exist": true,
       "verify_task_comment_content": true,
       "verify_milestone": true,

package/templates/.agents/skills/import-issue/SKILL.en.md

@@ -9,7 +9,7 @@ description: >
 > `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 
-Import the specified Issue and create a task. Argument: issue number.
+Import the specified Issue and create a task. Argument: a raw Issue token, parsed after the provider is selected.
 
 ## Boundary / Critical Rules
 
@@ -43,7 +43,7 @@ This skill **creates** task.md, so there is no file to write at the start. Captu
 
 Read `.agents/rules/issue-pr-commands.md` first, follow its prerequisite steps to complete authentication and code-hosting platform detection, then load the Issue data with its "Read an Issue" command.
 
-Extract: issue number, title, description, and labels.
+Extract: Issue identity, title, description, and labels.
 
 Derive the task title from the Issue title by stripping an optional single leading Conventional Commits prefix, following the contract below; preserve the rest of the description verbatim and in its original language. This fenced contract is the authoritative, language-neutral rule — keep it byte-for-byte identical across every `import-issue` variant:
 
@@ -67,7 +67,7 @@ Strip only the first layer, and only when the leading token is a `prefix-types`
 - If found, **reuse the existing task by default** (Scenario A); do not ask the user. State clearly in the final notice: "Reused existing task `{task-id}`; not re-imported." If the user wants to re-import, they must first archive or delete the existing task and run this skill again
 - If not found, continue to 2.2
 
-2.2 Run `agent-infra-internal platform-comment list --issue {issue-number}` to scan registered markers for a recoverable historical task ID.
+2.2 Run `agent-infra-internal platform-comment list --issue {issue-token}` to scan registered markers for a recoverable historical task ID.
 
 This command depends on `$upstream_repo` being set in step 1.
 
@@ -101,7 +101,7 @@ date +%Y%m%d-%H%M%S
 Task metadata:
 ```yaml
 id: {task-id}
-issue_number: <issue-number>
+platform_issue_identity: <canonical identity JSON string returned by the provider>
 type: feature|bugfix|refactor|docs|chore
 branch: <project>-<type>-<slug>
 workflow: feature-development|bug-fix|refactoring
@@ -146,8 +146,8 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 
 ### 5. Bind and Sync the Issue
 
-If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure):
-- Run `agent-infra-internal platform-issue bind {task-id} --issue {issue-number} --agent {standard-agent-token}`
+After creating task.md, always perform the following binding and sync actions (skip and continue on any platform failure):
+- Run `agent-infra-internal platform-issue bind {task-id} --issue {issue-token} --agent {standard-agent-token}`; the provider parses the token and atomically writes `platform_issue_identity`
 - Run `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --assignees current --milestone initial`
 - After every scenario, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
 
@@ -202,7 +202,7 @@ Next step - run requirements analysis:
 ## Completion Checklist
 
 - [ ] Created the task file `.agents/workspace/active/{task-id}/task.md`
-- [ ] Recorded `issue_number` in task.md
+- [ ] Provider wrote the Issue identity to `platform_issue_identity` in task.md
 - [ ] Updated `current_step` to requirement-analysis
 - [ ] Updated `updated_at` to the current time
 - [ ] Appended an Activity Log entry to task.md
@@ -224,6 +224,6 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 ## Error Handling
 
-- Issue not found: output "Issue #{number} not found, please check the issue number"
+- Issue not found: output "Issue {issue-token} not found, please check the Issue token"
 - Network error: output "Cannot connect to the platform, please check network"
 - Permission error: output "No access to this repository"

package/templates/.agents/skills/import-issue/SKILL.zh-CN.md

@@ -9,7 +9,7 @@ description: >
 > `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 
-导入指定的 Issue 并创建任务。参数：issue 编号。
+导入指定的 Issue 并创建任务。参数：Issue 原始 token，由选定 provider 解析。
 
 ## 行为边界 / 关键规则
 
@@ -43,7 +43,7 @@ description: >
 
 执行前先读取 `.agents/rules/issue-pr-commands.md`，并按其中的前置步骤完成认证和代码托管平台检测；随后按其中的 “读取 Issue” 命令获取 Issue 信息。
 
-提取：issue 编号、标题、描述、标签。
+提取：Issue identity、标题、描述、标签。
 
 从 Issue 标题派生任务标题：按下方契约剥掉可选的单层前导 Conventional Commits 前缀，其余描述原文与原始语言保持不变。下方 fenced 契约是权威的、与语言无关的规则——在所有 `import-issue` 变体中保持逐字节一致：
 
@@ -67,7 +67,7 @@ example-single-layer: "feat: add A: B" => "add A: B"
 - 如果找到，**默认复用现有任务**（场景 A），不询问用户；在最终告知中明确「已复用现有任务 `{task-id}`，未重新导入」。若用户希望重新导入，需要先手动归档/删除已有任务再次执行本技能
 - 如果未找到，继续执行 2.2
 
-2.2 调用 `agent-infra-internal platform-comment list --issue {issue-number}` 扫描注册 marker，查找可恢复的历史任务 ID。
+2.2 调用 `agent-infra-internal platform-comment list --issue {issue-token}` 扫描注册 marker，查找可恢复的历史任务 ID。
 
 该命令内部解析 upstream、认证与分页。
 
@@ -101,7 +101,7 @@ date +%Y%m%d-%H%M%S
 任务元数据：
 ```yaml
 id: {task-id}
-issue_number: <issue-number>
+platform_issue_identity: <provider 返回的 canonical identity JSON 字符串>
 type: feature|bugfix|refactor|docs|chore
 branch: <project>-<type>-<slug>
 workflow: feature-development|bug-fix|refactoring
@@ -146,8 +146,8 @@ date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 
 ### 5. 绑定并同步 Issue
 
-如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
-- 调用 `agent-infra-internal platform-issue bind {task-id} --issue {issue-number} --agent {standard-agent-token}` 校验并原子绑定
+创建 task.md 后始终执行以下绑定和同步操作（任一平台失败则跳过并继续）：
+- 调用 `agent-infra-internal platform-issue bind {task-id} --issue {issue-token} --agent {standard-agent-token}`，由 provider 解析并原子写入 `platform_issue_identity`
 - 调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --assignees current --milestone initial`
 - 所有场景结束后，必须调用 `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
 
@@ -202,7 +202,7 @@ Issue #{number} 已导入。
 ## 完成检查清单
 
 - [ ] 创建了任务文件 `.agents/workspace/active/{task-id}/task.md`
-- [ ] 在 task.md 中记录了 issue_number
+- [ ] 已由 provider 将 Issue identity 写入 task.md 的 `platform_issue_identity`
 - [ ] 更新了 `current_step` 为 requirement-analysis
 - [ ] 更新了 `updated_at` 为当前时间
 - [ ] 追加了 Activity Log 条目到 task.md
@@ -224,6 +224,6 @@ Issue #{number} 已导入。
 
 ## 错误处理
 
-- Issue 未找到：提示 "Issue #{number} not found, please check the issue number"
+- Issue 未找到：提示 "Issue {issue-token} not found, please check the Issue token"
 - 网络错误：提示 "Cannot connect to the platform, please check network"
 - 权限错误：提示 "No access to this repository"

package/templates/.agents/skills/import-issue/config/verify.json

@@ -15,13 +15,13 @@
         "assigned_to"
       ],
       "expected_step": "requirement-analysis",
-      "require_issue_number": true
+      "require_platform_issue_identity": true
     },
     "activity-log": {
       "expected_action_pattern": "Import Issue"
     },
     "platform-sync": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "issue_must_exist": true,
       "verify_task_comment_content": true
     }

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

@@ -114,7 +114,7 @@ Before writing this round's `{plan-artifact}`, create the controlled report skel
 agent-infra-internal task-artifact {task-id} init --family plan --artifact {plan-artifact} --locale en
 ```
 
-The skeleton contains identity metadata, stable section markers, and required headings only; real plan content is required before the completion gate can pass. If the finalizer returns one provably safe structural error, call `task-artifact {task-id} repair --family plan --artifact {plan-artifact} --expected-sha256 {artifact-sha256} --expected-semantic-digest {semantic-digest}`, then rerun the same finalizer.
+The skeleton contains identity metadata, stable section markers, and required headings only; real plan content is required before the completion gate can pass. If the finalizer returns one provably safe structural error, it returns a controlled recovery candidate; edit only its `candidatePath`, then rerun `task-artifact {task-id} finalize-local --family plan --artifact {plan-artifact} --recovery-id {recovery-id}` with the same `recoveryId`. Candidate-only is a protocol authorization boundary, not OS isolation; arbitrary same-UID host writers are outside the protocol's protection claim, and fingerprint/state checks fail closed on anomalies.
 
 Create `.agents/workspace/active/{task-id}/{plan-artifact}`.
 
@@ -135,14 +135,14 @@ agent-infra-internal task-artifact {task-id} finalize-local --family plan --arti
 ```
 
 - On `status=passed`, save that result's `artifactSha256` and `semanticDigest`; the finalizer has recorded the matching one-shot local provenance intent.
-- On `status=failed` with `repairable=true`, apply only the diagnostic's `replace-line` operation once, then rerun the same command completely; count an attempt only after bytes change, up to 8 attempts.
-- The first repairable failure's `semanticDigest` is retained as the baseline; a retried `status=passed` result must match it. On baseline mismatch, any other failure, no progress, or a repeated diagnostic, stop without publishing a completed event.
+- On `status=failed` with recovery context, edit only the returned `candidatePath` once after the completion gates pass, then rerun the finalizer completely with the same `recoveryId`; the formal artifact must remain unchanged until commit.
+- The recovery candidate must match the recorded task, round, artifact, baseline, and request identity. On baseline conflict, unknown state, no progress, or repeated failure, stop without publishing a completed event.
 
 Use the digests from that same `status=passed` result in `agent-infra-internal task-event {task-id} plan.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {plan-artifact} --artifact-sha256 {artifact-sha256} --semantic-digest {semantic-digest} {execution-flag}` so the core records the link, stage, agent, metadata, and Activity Log atomically.
   - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Plan Task (Round {N})** by {agent} — Plan completed, awaiting human review → {artifact-filename}
   ```
 
-If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure):
+If task.md contains a valid `platform_issue_identity`, perform these sync actions (skip and continue on any failure):
 - Run `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status pending-design-work --fields`
 - Run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`
 - Run `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {plan-artifact} --agent {standard-agent-token}`

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

@@ -117,7 +117,7 @@ agent-infra-internal task-event {task-id} plan.started --agent {standard-agent-t
 agent-infra-internal task-artifact {task-id} init --family plan --artifact {plan-artifact}
 ```
 
-骨架只包含身份元数据、稳定 section marker 和必需标题；必须填入真实方案内容后才能通过完成门禁。finalizer 返回可证明的单个结构错误时，使用其 SHA 和 semantic digest 调用 `task-artifact {task-id} repair --family plan --artifact {plan-artifact} --expected-sha256 {artifact-sha256} --expected-semantic-digest {semantic-digest}`，然后完整重跑 finalizer。
+骨架只包含身份元数据、稳定 section marker 和必需标题；必须填入真实方案内容后才能通过完成门禁。finalizer 返回可证明的单个结构错误时，会返回受控 recovery candidate；只能编辑返回的 `candidatePath`，然后使用同一个 `recoveryId` 重跑 `task-artifact {task-id} finalize-local --family plan --artifact {plan-artifact} --recovery-id {recovery-id}`。candidate-only 是协议授权边界，不是操作系统隔离；同 UID 的任意宿主写入者不在本协议的防护承诺内，异常由指纹/状态校验失败关闭。
 
 创建 `.agents/workspace/active/{task-id}/{plan-artifact}`。
 
@@ -134,11 +134,11 @@ agent-infra-internal task-artifact {task-id} init --family plan --artifact {plan
   agent-infra-internal task-artifact {task-id} finalize-local --family plan --artifact {plan-artifact}
   ```
   - `status=passed`：保存本次返回的 `artifactSha256` 和 `semanticDigest`；finalizer 已记录对应的一次性本地 provenance intent。
-  - `status=failed` 且 `repairable=true`：仅按诊断中的 `replace-line` 操作做一次最小修改，然后完整重跑同一命令；实际字节发生变化才计一次 `repairAttempts`，最多 8 次。
-  - 首次可修复失败的 `semanticDigest` 由 finalizer 保留为基线；重试后的 `status=passed` 必须匹配该基线。基线不匹配、其他失败、无进展或重复诊断：停止，不发布 completed 事件。
+  - `status=failed` 且返回 recovery context：完成门禁通过后，只编辑返回的 `candidatePath` 一次，然后使用同一个 `recoveryId` 完整重跑 finalizer；formal artifact 在 commit 前必须保持不变。
+  - recovery candidate 必须与记录的任务、轮次、产物、baseline 和 request identity 匹配；基线冲突、未知状态、无进展或重复失败：停止，不发布 completed 事件。
 - 使用同一次 `status=passed` 返回的摘要执行 `agent-infra-internal task-event {task-id} plan.completed --agent {standard-agent-token} --initiator {trigger-initiator} --request-id {request-id} --reason-code {reason-code} --artifact {plan-artifact} --artifact-sha256 {artifact-sha256} --semantic-digest {semantic-digest} {execution-flag}`，由核心登记链接、阶段、代理、时间、版本和 Activity Log。
 
-如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
+如果 task.md 中存在有效的 `platform_issue_identity`，执行以下同步操作（任一失败则跳过并继续）：
 - 调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status pending-design-work --fields`
 - 调用 `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 {plan-artifact} --agent {standard-agent-token}`

package/templates/.agents/skills/plan-task/config/verify.en.json

@@ -28,7 +28,7 @@
       ]
     },
     "platform-sync": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "expected_status_label": "status: pending-design-work",
       "expected_comment_marker": "<!-- sync-issue:{task-id}:{artifact-stem} -->",
       "verify_comment_content": true,

package/templates/.agents/skills/plan-task/config/verify.zh-CN.json

@@ -28,7 +28,7 @@
       ]
     },
     "platform-sync": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "expected_status_label": "status: pending-design-work",
       "expected_comment_marker": "<!-- sync-issue:{task-id}:{artifact-stem} -->",
       "verify_comment_content": true,

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

@@ -33,7 +33,7 @@ Comment parsing must not write the formal active directory. Step 6 declares one
 ### 1. Verify Input and Environment
 
 Check:
-- required `{issue-number}`
+- required `{issue-token}`
 - optional `{task-id}`
 - read `.agents/rules/issue-pr-commands.md` first and use its authentication commands to verify current platform access
 
@@ -41,17 +41,18 @@ If the user provided `{task-id}`, validate the `TASK-{yyyyMMdd-HHmmss}` format.
 
 ### 2. Fetch Issue Comments
 
-Run `agent-infra-internal platform-comment list --issue {issue-number}` to read all paginated comments while preserving order and comment IDs; the intent owns platform context, authentication, and upstream resolution.
+Run `agent-infra-internal platform-comment list --issue {issue-token}` to read all paginated comments while preserving order and comment IDs; the intent owns platform context, authentication, and upstream resolution.
 
 ### 3. Determine the task-id and Files to Restore
 
-Filter comments by the task, artifact, and chunked artifact markers defined in `.agents/rules/issue-sync.md`.
+Filter comments by the task, artifact, chunked artifact, and recovery markers defined in `.agents/rules/issue-sync.md`.
 
 Rules:
 - when `{task-id}` was provided, match only that task
 - when `{task-id}` was omitted, infer it from the task comment marker first
 - if you cannot determine a unique task-id, stop and tell the user
 - ignore `summary` marker comments because they are complete-task aggregate output rather than restorable local task files
+- use the `task` comment only for the current projection and snapshot identity; the controlled recovery core validates `recovery-action`, `recovery-prepare`, and `recovery-commit` comments and reconstructs the complete `task.md`
 - map `{file-stem}` back to filenames:
   - `task` -> `task.md`
   - `analysis` / `analysis-r{N}` -> matching `.md`
@@ -68,7 +69,7 @@ Read `.agents/rules/issue-sync.md` before executing this step.
 
 For each file:
 - collect its single comment or chunked comments
-- for `task.md` comments, reverse the `<details>` frontmatter wrapper described in issue-sync.md before reassembling the file body
+- do not reverse the projected task comment directly into `task.md`; the complete task content must come from a recovery commit matching the current projection
 - when a chunk marker includes part and total indexes, sort by part and verify the set is complete
 - extract the file body by removing the hidden marker, heading, and footer
 - concatenate chunk bodies into the final file content
@@ -83,10 +84,14 @@ If the directory already exists, stop immediately and tell the user to handle it
 
 Create the controlled staging directory and write files back in this order:
 
-1. `task.md`
+1. call the recovery core to write `task.md`:
+   ```bash
+   agent-infra-internal platform-comment recover --issue {issue-token} --task-id {task-id} \
+     --output "{staging-dir}/task.md"
+   ```
 2. every other restored artifact file in filename order
 
-Write only files that were actually recovered from Issue comments. Do not invent missing files.
+Write only files that were actually recovered from Issue comments. Do not invent missing files. Stop without calling the lifecycle intent if the recovery core fails.
 
 ### 6. Apply the Restore Lifecycle Intent
 

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

@@ -32,7 +32,7 @@ description: >
 ### 1. 验证输入与环境
 
 检查：
-- 必填参数 `{issue-number}`
+- 必填参数 `{issue-token}`
 - 可选参数 `{task-id}`
 - 执行前先读取 `.agents/rules/issue-pr-commands.md`，并按其中的认证命令验证当前平台访问能力
 
@@ -40,17 +40,18 @@ description: >
 
 ### 2. 获取 Issue 评论
 
-调用 `agent-infra-internal platform-comment list --issue {issue-number}` 读取全部分页评论，保留原始顺序和评论 ID；平台上下文、认证和 upstream 由 internal intent 处理。
+调用 `agent-infra-internal platform-comment list --issue {issue-token}` 读取全部分页评论，保留原始顺序和评论 ID；平台上下文、认证和 upstream 由 internal intent 处理。
 
 ### 3. 确定 task-id 与待恢复文件
 
-按 `.agents/rules/issue-sync.md` 中定义的 task、artifact 和分片 artifact 标记筛选评论。
+按 `.agents/rules/issue-sync.md` 中定义的 task、artifact、分片 artifact 和 recovery 标记筛选评论。
 
 处理规则：
 - 用户提供了 `{task-id}` 时，仅匹配该任务
 - 未提供时，优先从 task 评论标记推断
 - 若找不到唯一 task-id，立即停止并告知用户
 - 忽略 `summary` 标记评论；它是 complete-task 的聚合产物，不对应本地任务文件
+- `task` 评论仅用于确定当前投影和 snapshot 身份；`recovery-action`、`recovery-prepare`、`recovery-commit` 由受控 recovery core 验证并重建完整 `task.md`
 - 将 `{file-stem}` 映射回文件名：
   - `task` -> `task.md`
   - `analysis` / `analysis-r{N}` -> 对应 `.md`
@@ -67,7 +68,7 @@ description: >
 
 对每个文件执行：
 - 收集单条评论或分片评论
-- 对 `task.md` 评论按 issue-sync.md 中的 `<details>` frontmatter 格式反向拆解，提取 frontmatter 后再与正文拼合
+- 不直接把投影 task 评论反向拆成 `task.md`；完整 task 内容必须来自匹配当前投影的 recovery commit
 - 如分片标记中存在 part 和 total 序号，按 part 升序排序并校验分片完整
 - 从评论正文中提取文件内容，去掉隐藏标记、标题和页脚
 - 拼接得到最终文件内容
@@ -82,10 +83,14 @@ description: >
 
 创建受控 staging 目录，按以下顺序写回：
 
-1. `task.md`
+1. 调用 recovery core 写入 `task.md`：
+   ```bash
+   agent-infra-internal platform-comment recover --issue {issue-token} --task-id {task-id} \
+     --output "{staging-dir}/task.md"
+   ```
 2. 其余产物文件（按文件名排序）
 
-仅写回从 Issue 评论中实际恢复出的文件，不补造缺失文件。
+仅写回从 Issue 评论中实际恢复出的文件，不补造缺失文件。recovery core 返回失败时停止，不调用 lifecycle intent。
 
 ### 6. 执行 restore 生命周期意图
 

package/templates/.agents/skills/restore-task/config/verify.json

@@ -14,7 +14,7 @@
         "assigned_to"
       ],
       "expected_status": "active",
-      "require_issue_number": true
+      "require_platform_issue_identity": true
     },
     "activity-log": {
       "expected_action_pattern": "Restore Task"

package/templates/.agents/skills/review-analysis/SKILL.en.md

@@ -75,7 +75,7 @@ Before writing this round's `{review-artifact}`, create the controlled review sk
 agent-infra-internal task-artifact {task-id} init --family review-analysis --artifact {review-artifact} --locale en
 ```
 
-The skeleton contains identity metadata, stable section markers, and required headings only; complete review content is required before summary finalization. If structural finalization returns one provably safe error, call `task-artifact {task-id} repair --family review-analysis --artifact {review-artifact} --expected-sha256 {artifact-sha256} --expected-semantic-digest {semantic-digest}`, then rerun the original finalizer.
+The skeleton contains identity metadata, stable section markers, and required headings only; complete review content is required before summary finalization. If structural finalization returns one provably safe error, it returns a controlled recovery candidate; edit only its `candidatePath`, then rerun the original finalizer with the same `recoveryId`. Candidate-only is a protocol authorization boundary, not OS isolation; arbitrary same-UID host writers are outside the protocol's protection claim, and fingerprint/state checks fail closed on anomalies.
 
 Create `.agents/workspace/active/{task-id}/{review-artifact}`.
 
@@ -83,7 +83,7 @@ Create `.agents/workspace/active/{task-id}/{review-artifact}`.
 
 ### 6. Update Task Status
 
-After the report, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`; submit prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, make the initial call to `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} {execution-flag}`; after a failure, follow `.agents/rules/local-artifact-repair.md` to decide whether to edit and rerun, and never treat an error type or `changed=false` as automatic authorization.
+After the report, call `agent-infra-internal task-review {task-id} preflight --stage analysis --artifact {review-artifact} {execution-flag}` before any ledger write. On failure, follow `.agents/rules/local-artifact-repair.md`; on success, bind `{recovery-id}` from the response. Only after preflight passes, submit each new finding with `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}` or prior-response dispositions with `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {evidence}`. Do not scan ids or edit ledger rows. After all ledger writes, call `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} --recovery-id {recovery-id} {execution-flag}`; never treat an error type or `changed=false` as automatic authorization.
 
 Bind and reuse this structured mapping from that one response:
 
@@ -97,7 +97,7 @@ The intent atomically finalizes the report summary and returns the same ledger s
 
 `manual-validation` is the data source for the `Manual-validation` count folded into review rows in `ai task log`; do not add a parallel manual-verification field.
 
-If task.md has a valid `issue_number`, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`, then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {review-artifact} --agent {standard-agent-token}`.
+If task.md has a valid `platform_issue_identity`, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {standard-agent-token}`, then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {review-artifact} --agent {standard-agent-token}`.
 
 Before writing the summary, the finalization intent checks decision-detail ids; any visible duplicate returns a structured failure and preserves the artifact bytes, while the model decides whether a minimal edit is safe under the shared rule. If the safety gates fail, diagnostics repeat, no byte-level progress occurs, or the emergency cap is reached, stop before the completion event; the stop path must still show the existing review result instead of hiding the artifact.
 

package/templates/.agents/skills/review-analysis/SKILL.zh-CN.md

@@ -78,7 +78,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 agent-infra-internal task-artifact {task-id} init --family review-analysis --artifact {review-artifact}
 ```
 
-骨架不生成审查结论、发现或计数；完成审查内容后才能进入 summary finalizer。结构 finalizer 返回可证明的单个错误时，使用其 SHA 和 semantic digest 调用 `task-artifact {task-id} repair --family review-analysis --artifact {review-artifact} --expected-sha256 {artifact-sha256} --expected-semantic-digest {semantic-digest}`，再重跑原 finalizer。
+骨架不生成审查结论、发现或计数；完成审查内容后才能进入 summary finalizer。结构 finalizer 返回可证明的单个错误时，会返回受控 recovery candidate；只能编辑返回的 `candidatePath`，然后使用同一个 `recoveryId` 重跑原 finalizer。candidate-only 是协议授权边界，不是操作系统隔离；同 UID 的任意宿主写入者不在本协议的防护承诺内，异常由指纹/状态校验失败关闭。
 
 创建 `.agents/workspace/active/{task-id}/{review-artifact}`。
 
@@ -86,7 +86,7 @@ agent-infra-internal task-artifact {task-id} init --family review-analysis --art
 
 ### 6. 更新任务状态
 
-报告完成后，新 finding 逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`；复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后首次调用 `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} {execution-flag}`；失败后是否继续编辑并重跑，必须遵循 `.agents/rules/local-artifact-repair.md`，不能把失败类型或 `changed=false` 当作自动授权。
+报告完成后，先调用 `agent-infra-internal task-review {task-id} preflight --stage analysis --artifact {review-artifact} {execution-flag}`，不得先写入账本。失败后是否继续编辑并重跑，必须遵循 `.agents/rules/local-artifact-repair.md`；通过时从返回值绑定 `{recovery-id}`。只有 preflight 通过后，才逐条调用 `agent-infra-internal task-ledger {task-id} finding-upsert --stage analysis --review-artifact {review-artifact} --ordinal {n} --severity {blocker|major|minor} --evidence {review-artifact}#{anchor}`，或复核上一轮响应时调用 `finding-review --id {ledger-id} --status {confirmed|closed|open|needs-human-decision} --evidence {相称证据}`。不得扫描编号或手写账本行。全部账本写入完成后调用 `agent-infra-internal task-review {task-id} finalize-summary --stage analysis --artifact {review-artifact} --recovery-id {recovery-id} {execution-flag}`；不能把失败类型或 `changed=false` 当作自动授权。
 
 从该次返回值绑定并复用以下结构化映射：
 
@@ -100,7 +100,7 @@ agent-infra-internal task-artifact {task-id} init --family review-analysis --art
 
 `manual-validation` 是 `ai task log` 中 review 行「人工校验点」（EN `Manual-validation`）计数的数据源；不要新增并行人工验证字段。
 
-如果 task.md 中存在有效的 `issue_number`，调用 `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 {review-artifact} --agent {standard-agent-token}`；失败按 `.agents/rules/issue-sync.md` 记录 warning。
+如果 task.md 中存在有效的 `platform_issue_identity`，调用 `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 {review-artifact} --agent {standard-agent-token}`；失败按 `.agents/rules/issue-sync.md` 记录 warning。
 
 最终化 intent 会在写入摘要前检查详情块 ID；任何可见重复都返回结构化失败并保持 artifact 字节不变，由模型按共享规则判断是否进行最小编辑。无法通过安全门、诊断重复、没有实际字节变化或达到紧急熔断时，停止在完成事件之前；停止路径仍必须展示已有审查结果，不得吞掉 artifact 内容。
 

package/templates/.agents/skills/review-analysis/config/verify.en.json

@@ -27,7 +27,7 @@
       "expected_action_pattern": "(Review Analysis|Analysis Review) \\(Round \\d+\\)"
     },
     "platform-sync": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "expected_status_label": "status: pending-design-work",
       "expected_comment_marker": "<!-- sync-issue:{task-id}:{artifact-stem} -->",
       "verify_comment_content": true,