@fitlab-ai/agent-infra 0.9.14 → 0.10.0

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

@@ -7,6 +7,7 @@ Read this file before creating `manual-validation.md` / `manual-validation-r{N}.
 
 - **Validation Round**: Round {N}
 - **Artifact File**: `manual-validation.md`
+- **Human Validation Basis**: Maintainer's PR validation comment and validation summary
 
 ## State Check
 
@@ -39,6 +40,7 @@ $ tail .agents/workspace/active/{task-id}/task.md
 - Result: {summary-result}
 - Summary comment: {comment-id or URL}
 - Updated status: `### ✅ Manual Validation Passed`
+- Transaction: `{transaction-id}`; receipt=`{receipt-digest}`; head=`{pr-head-sha}`
 ````
 
 ## Filling Rules

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

@@ -7,6 +7,7 @@
 
 - **验证轮次**：Round {N}
 - **产物文件**：`manual-validation.md`
+- **人工验证依据**：维护者提供的 PR 验证留言和验证说明
 
 ## 状态核对
 
@@ -39,6 +40,7 @@ $ tail .agents/workspace/active/{task-id}/task.md
 - 结果：{summary-result}
 - 摘要评论：{comment-id 或 URL}
 - 更新状态：`### ✅ 人工验证已通过`
+- Transaction：`{transaction-id}`；receipt=`{receipt-digest}`；head=`{pr-head-sha}`
 ````
 
 ## 填写规则

package/templates/.agents/skills/complete-manual-validation/reference/summary-update.en.md

@@ -4,14 +4,23 @@ Run only for a valid `{task-id}` whose task.md binds a verified `pr_delivery_fac
 
 Follow `.agents/rules/pr-sync.md` for the shared summary structure and failure semantics.
 
-1. After the canonical `manual-validation*` artifact is written, run `agent-infra-internal platform-pr summary-context {task-id}`.
-2. Rebuild the summary from canonical inputs and render `### ✅ Manual Validation Passed` with the validation time and explanation.
-3. Write the plain body with exactly one `<!-- canonical-pr-change-report -->` placeholder to a temporary file and run:
+1. Run `agent-infra-internal platform-pr summary-context {task-id}` to obtain the canonical summary body; the maintainer's PR validation comment and validation summary are the human-validation authority.
+2. Before creating the canonical `manual-validation*` artifact, call the transaction coordinator in prepare mode to record `started` before writing the prepared transaction:
 
 ```bash
-agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {standard-agent-token} --body-file {summary-body-file} \
-  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json --result no_op
+agent-infra-internal manual-validation transaction {task-id} --prepare \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} --agent {standard-agent-token}
 ```
 
-The core owns the rendered report, marker/authoritative PR-head wrapping, pagination, and in-place reconciliation. If context says no manual validation is required, stop without marking it passed.
+3. After prepare succeeds, write the canonical `manual-validation*` artifact, write the pending plain body with exactly one `<!-- canonical-pr-change-report -->` placeholder to a temporary file, and run the transaction coordinator:
+
+```bash
+agent-infra-internal manual-validation transaction {task-id} \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} \
+  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --agent {standard-agent-token} --result no_op
+```
+
+The core owns the rendered report, marker/authoritative PR-head wrapping, pagination, pending-first ordering, receipt, completion log, final promotion, and in-place reconciliation. Before the receipt and completion log exist, the summary must not contain `### ✅ Manual Validation Passed`. If context says no manual validation is required, stop without marking it passed.

package/templates/.agents/skills/complete-manual-validation/reference/summary-update.zh-CN.md

@@ -4,16 +4,25 @@
 
 摘要结构与失败语义统一遵循 `.agents/rules/pr-sync.md`。
 
-1. 在 canonical `manual-validation*` artifact 落盘后，调用 `agent-infra-internal platform-pr summary-context {task-id}`。
-2. 从返回的最新产物重新聚合摘要，将人工校验段渲染为 `### ✅ 人工验证已通过`，写明验证时间和说明。
-3. 把只含一次 `<!-- canonical-pr-change-report -->` 的纯正文写入临时文件，调用：
+1. 调用 `agent-infra-internal platform-pr summary-context {task-id}`，取得 canonical 摘要正文；维护者提供的 PR 人工验证留言和验证说明作为完成人工校验依据。
+2. 在创建 canonical `manual-validation*` artifact 前，调用 transaction coordinator 的 prepare 模式，先登记 started，再写 prepared transaction：
 
 ```bash
-agent-infra-internal platform-pr summary-sync {task-id} \
-  --agent {standard-agent-token} --body-file {summary-body-file} \
-  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json --result no_op
+agent-infra-internal manual-validation transaction {task-id} --prepare \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} --agent {standard-agent-token}
 ```
 
-marker、报告段、权威 PR head、分页查找和原地更新由 core 负责。若当前 context 表明无需人工校验，则停止并返回 `summary failed: no manual validation required`，不误标通过。
+3. prepare 成功后写入 canonical `manual-validation*` artifact，并把只含一次 `<!-- canonical-pr-change-report -->` 的 pending 正文写入临时文件，调用 transaction coordinator：
+
+```bash
+agent-infra-internal manual-validation transaction {task-id} \
+  --artifact {manual-validation-artifact} \
+  --summary-file {summary-body-file} \
+  --change-report-file .agents/workspace/active/{task-id}/pr-change-report.json \
+  --agent {standard-agent-token} --result no_op
+```
+
+marker、报告段、权威 PR head、分页查找、pending-first 顺序、receipt、通过日志和 final promotion 由 core 负责。若当前 context 表明无需人工校验，则停止并返回 `summary failed: no manual validation required`，不误标通过。receipt/log 前不得出现 `### ✅ 人工验证已通过`。
 
 结果回传：`summary updated`、`summary skipped (no diff)` 或 `summary failed: <reason>`。

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

@@ -104,7 +104,7 @@ Run /create-pr --task {task-ref} first, then complete; --skip-pr is not accepted
 Before lifecycle, verify only the hard gates:
 - [ ] Task identity, active state, concurrency locks, and local atomic lifecycle operations are available
 - [ ] Required-PR delivery is satisfied when `prFlow=required`
-- [ ] Other business evidence (workflow, review, commit, tests, disagreement ledger, manual validation, and platform sync) is recorded or can be checked after lifecycle
+- [ ] Other business evidence (workflow, review, commit, tests, disagreement ledger, manual validation, and platform sync) is recorded or can be checked after lifecycle; manual validation requires a committed transaction, receipt, current artifact digest, and an identity-bearing completion log
 
 > **⚠️ Prerequisite Branch Check — you must decide whether to continue or stop before proceeding:**
 >
@@ -135,11 +135,11 @@ Do not write `status/current_step/completed_at/updated_at/agent_infra_version`,
 
 ### 4. Sync the Platform While Active
 
-Check whether task.md has a valid `issue_number`. If it does not, skip this step without output.
+Check whether task.md has a valid `platform_issue_identity`. If it does not, skip this step without output.
 
 > Issue metadata boundaries live in `.agents/rules/issue-sync.md`; comments use internal platform intents.
 
-When an `issue_number` exists, execute in this exact order:
+When a valid `platform_issue_identity` exists, execute in this exact order:
 
 1. Run `agent-infra-internal platform-comment backfill {task-id} --agent {standard-agent-token}` so core publishes only the completion canonical inventory in fixed order and resolves matching historical warnings only after full success.
 2. Run `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --requirements --fields`.

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

@@ -103,7 +103,7 @@ agent-infra-internal platform-pr resolve-external {task-id} --agent {standard-ag
 生命周期前只验证硬门禁：
 - [ ] task 身份、active 状态、并发锁和本地原子生命周期操作可用
 - [ ] `prFlow=required` 时已满足 required-PR delivery
-- [ ] 其余业务证据（工作流、审查、提交、测试、分歧账本、人工校验和平台同步）已记录或可在生命周期后校验
+- [ ] 其余业务证据（工作流、审查、提交、测试、分歧账本、人工校验和平台同步）已记录或可在生命周期后校验；人工验证只能由 committed transaction、receipt、当前 artifact 摘要和带 identity 的通过日志满足
 
 > **⚠️ 前置条件分支判断 — 你必须先判断“继续”还是“停止”：**
 >
@@ -134,11 +134,11 @@ Please satisfy the hard prerequisite first, then retry complete-task.
 
 ### 4. 在 active 阶段同步平台
 
-检查 `task.md` 中是否存在有效的 `issue_number`。如果没有，跳过本步骤且不输出任何内容。
+检查 `task.md` 中是否存在有效的 `platform_issue_identity`。如果没有，跳过本步骤且不输出任何内容。
 
 > Issue 元数据边界见 `.agents/rules/issue-sync.md`；评论同步统一调用 internal platform intent。
 
-如果存在有效的 `issue_number`，严格按以下顺序执行：
+如果存在有效的 `platform_issue_identity`，严格按以下顺序执行：
 
 1. 调用 `agent-infra-internal platform-comment backfill {task-id} --agent {standard-agent-token}`，由 core 仅按 completion canonical inventory 固定顺序补发产物并在全部成功后精确恢复目标历史告警。
 2. 调用 `agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --requirements --fields`。

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

@@ -28,7 +28,7 @@
     "manual-validation": {},
     "post-review-commit": {},
     "platform-sync-preflight": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "expected_comment_marker": "<!-- sync-issue:{task-id}:summary -->",
       "verify_task_comment_content": false,
       "sync_checked_requirements": true,
@@ -40,7 +40,7 @@
     },
     "required-pr-delivery": {},
     "platform-sync": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "verify_task_comment_content": true,
       "verify_closed_issue_has_no_status_labels": true
     },

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

@@ -28,7 +28,7 @@
     "manual-validation": {},
     "post-review-commit": {},
     "platform-sync-preflight": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "expected_comment_marker": "<!-- sync-issue:{task-id}:summary -->",
       "verify_task_comment_content": false,
       "sync_checked_requirements": true,
@@ -40,7 +40,7 @@
     },
     "required-pr-delivery": {},
     "platform-sync": {
-      "when": "issue_number_exists",
+      "when": "platform_issue_identity_exists",
       "verify_task_comment_content": true,
       "verify_closed_issue_has_no_status_labels": true
     },

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,