@fitlab-ai/agent-infra 0.9.10 → 0.9.12

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

@@ -7,7 +7,7 @@ description: >
 ---
 
 # 编码任务
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 若入口业务操作数包含 `--orchestrated`，绑定 `{execution-flag}` = `--orchestrated` 并原样转发给 completed 事件；否则绑定为空。不得从 `orchestration.json`、环境变量或历史产物推断该标记。
 
@@ -16,10 +16,11 @@ description: >
 ## 行为边界 / 关键规则
 
 - 严格遵循最新方案产物：`plan.md` 或 `plan-r{N}.md`
+- 生成会同步到 Issue 的任务或生命周期 Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；同步端不解析或改写正文
 - 实现前读取 `.agents/rules/compatibility-policy.md`；只实现方案明确批准的兼容预算，不以“稳妥”为由保留旧分支、旧结果契约或迁移 shim
 - 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；manual-validation 项不在修复范围
 - 实现中遇到方案未覆盖的关键设计决策时，先调用 `agent-infra-internal task-ledger {task-id} decision-next-id` 取得 `HD-N`，按 `.agents/rules/human-decision-context.md` 写入实现报告的 `## 人工裁决待办` 详情块并判断是否需要实现，再调用 `decision-upsert --id {HD-N} --stage code --artifact {code-artifact} --needs-implementation {true|false}`；不得扫描编号、手写账本行、中途提问或擅自扩范围
-- 绝不自动执行 `git add` 或 `git commit`
+- 不调用 `commit` 技能，也不推送远端；测试通过后直接调用共享 commit core 的 `delivery: { mode: 'local' }` 创建本地 checkpoint。checkpoint 使用 durable intent，只有 checkpoint 与 task 状态同步成功后才发送 `code.completed`
 - 每轮实现都创建新的实现产物，不覆盖旧文件
 - 执行本技能后，你**必须**立即更新 task.md
 
@@ -34,7 +35,7 @@ description: >
 | 「代码太简单，不需要测试」 | 简单代码也会回归；没有"失败→通过"的用例就没有完成标志，先写验证业务行为的测试。 |
 | 「先写代码再补测试更高效」 | 后补测试常沦为对实现的镜像；目标驱动应先定义可验证用例再让它通过。 |
 | 「方案这里不合理，顺手改更好」 | 偏离 `{plan-artifact}` 必须在报告中记录原因；有异议先停下确认，不擅自改方向。 |
-| 「测试过了，顺便提交一下」 | 本技能绝不执行 `git add`/`git commit`，提交是用户显式发起的独立步骤。 |
+| 「测试过了，顺便推送一下」 | 本技能只创建本地 checkpoint；远端推送是 `create-pr` 的唯一边界。 |
 | 「审查既然写了，照着改就行」 | 审查可能基于错误 `file:line` 或幻觉；动手前先 Read/Grep 核实，成立才修，不成立就反驳并记入 unresolved，不盲从。 |
 | 「保留旧入口更稳妥，反正只多一个分支」 | 未获批准的兼容是范围扩张和长期债务；没有对象、必要性、期限和退出条件就只实现当前契约。 |
 
@@ -42,7 +43,7 @@ description: >
 
 在加载 workflow / skill / rules 指令之后、做任何任务状态判断或用户可见结论之前，必须先执行状态核对。指令类文件读取不算对外动作或结论。
 
-运行以下命令，并把原文粘贴到回复正文和本轮产物的 `## 状态核对` 段：
+运行以下命令，并把原文粘贴到本轮产物的 `## 状态核对` 段：
 
 ```bash
 agent-infra-internal task-snapshot {task-id} --format text
@@ -52,7 +53,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 ## 任务上下文解析
 
-> 入口允许省略 task ref，也接受旧位置 task ref 或 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空、位置 ref 或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
+> 入口可省略 task ref；显式 task scope 仅接受 `--task <ref>` 或 `-t <ref>`，不再解释位置 task ref。保留其余业务操作数后调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
 
 > 解析任务引用，并确认任务位于本技能支持的状态或目录且存在 `task.md`；无法定位时按未找到任务处理并停止。
 
@@ -141,6 +142,8 @@ echo "$result"
 
 如果测试失败，先尝试修复并重新运行测试。只有在确认存在外部阻塞、环境缺失或需求不明确且超出任务范围时，才可以停止。
 
+测试通过后，通过 `agent-infra-internal git-workflow commit --input {checkpoint-input}` 调用共享 commit core，输入 `delivery: { "mode": "local" }`、明确 paths、expected HEAD/tree、task ref、agent 和 code round。该调用只创建本地 checkpoint，不访问远端；core 会在 commit 前写入 durable intent，并在 task writer 成功后清理 intent。checkpoint 失败或 task 状态未闭合时，不得发送 `code.completed`。
+
 排查测试失败或行为不符合预期时，先读取 `.agents/rules/debugging-guide.md`，按其四阶段流程定位根因，禁止盲目改代码重试。
 
 ### 9. 编写实现报告
@@ -197,7 +200,7 @@ agent-infra-internal task-verify {task-id} code.completed --artifact {code-artif
 
 ## 停止
 
-完成检查清单后立即停止。不要自动提交。
+完成检查清单后立即停止。不要在本技能中推送远端、创建 PR 或调用 `commit` 技能。
 
 ## 注意事项
 

package/templates/.agents/skills/commit/SKILL.en.md

@@ -7,21 +7,21 @@ description: >
 
 # Commit code
 
-Use the standard agent token from `.agents/rules/task-management.md`.
+> See the collaborator token convention in `.agents/rules/task-management.md` for valid `--agent` values.
 
-Create a Git commit without overwriting local work, and update the associated task only when a task context exists.
+Create a Git commit without overwriting local work, and update the associated task state when needed.
 
 The commit core returns one primary result: `committed`, `no_op`, `committed_with_warnings`, `failed`, or `blocked`, with structured `warnings`. A push failure or protected-branch policy never rolls back a local commit.
 
 ## Task context
 
-Resolve the optional task scope with `agent-infra-internal task-context resolve {task-scope}`.
+The entry point may omit the task ref; explicit task scope accepts only `--task <ref>` or `-t <ref>`, and positional task refs are not interpreted. First call `agent-infra-internal task-context resolve {task-scope}`.
 
 - An explicit task-resolution failure stops the operation.
 - Without an explicit task scope, only `TASK_CONTEXT_NOT_FOUND` may enter taskless direct mode; detached HEAD, malformed candidates, and multiple matches fail closed.
-- If the literal `--orchestrated` is present in the business operands, use `mode=orchestrated`; otherwise use `mode=direct`. Never infer the mode from files or environment.
+- If the literal `--orchestrated` is present in the business operands, fail with `ORCHESTRATED_COMMIT_REMOVED` because the standalone commit stage has been removed; otherwise use `mode=direct`. Never infer the mode from files or environment.
 - Taskless direct mode does not read, create, or complete task intent, receipt, checkpoint, or task.md records.
-- Task-bound direct mode does not require a delegation receipt; orchestrated mode must validate the matching activated commit receipt and capability in the core.
+- Task-bound direct mode does not require a delegation receipt; `code-task` calls the shared core for local checkpoints, while standalone `commit` continues to use push delivery.
 - After resolution, use only the core-returned `taskId`; never infer task identity from the environment, branch, or filename.
 
 ## 1. Inspect local changes
@@ -33,7 +33,7 @@ git status --short
 git diff
 ```
 
-Respect existing user changes and stop on a conflict according to the no-mid-flow-questions rule.
+Respect existing user changes. If the planned work conflicts with them, stop and record the blocking reason according to the no-mid-flow-questions rule.
 
 ## 2. Update copyright years
 
@@ -47,13 +47,31 @@ Review status, diff, and recent history. Use an imperative Conventional Commit m
 
 Read `reference/commit-orchestration.md` before this step.
 
-Write the message, explicit paths, expected HEAD/tree, task scope, agent, mode, and optional push policy to a temporary JSON file, then call:
+Write the message, explicit paths, expected HEAD/tree, task scope, agent, mode, and required push policy to a temporary JSON file, then call:
 
 ```bash
 agent-infra-internal git-workflow commit --input {commit-operation.json}
 ```
 
-Taskless direct mode omits `taskRef`; orchestrated mode must pass `taskRef`, `agent`, and `mode: "orchestrated"`. The core owns repository/worktree mutation locking, task locking when bound, path and sensitive-file checks, staged scope, HEAD/tree, branch/ref, commit, push, protected-branch policy, warnings, and idempotency.
+Example:
+
+```json
+{
+  "taskRef": "TASK-YYYYMMDD-HHMMSS",
+  "agent": "codex",
+  "mode": "direct",
+  "paths": ["lib/example.ts", "tests/example.test.ts"],
+  "message": "fix(core): validate example input",
+  "expectedHead": "{HEAD}",
+  "expectedTree": "{TREE}",
+  "push": {
+    "remote": "origin",
+    "refs": ["refs/heads/{branch}"]
+  }
+}
+```
+
+Taskless direct mode omits `taskRef`; direct task-bound commits use push delivery. The core owns repository/worktree mutation locking, task locking when bound, path and sensitive-file checks, staged scope, HEAD/tree, branch/ref, commit, push, protected-branch policy, warnings, and idempotency.
 
 - Create at most one local commit for explicit changes.
 - If there are no changes but HEAD is ahead and delivery is requested, perform push-only and do not create an empty commit.
@@ -63,7 +81,9 @@ Taskless direct mode omits `taskRef`; orchestrated mode must pass `taskRef`, `ag
 
 ## 5. Finish task and platform synchronization
 
-Continue task synchronization only for task-bound operations. For an associated Issue or PR, follow the issue, PR-summary, and platform rules; the commit path passes `--result no_op` to summary-sync because it only synchronizes an existing PR identity. Synchronization failures are warnings and do not roll back the local commit.
+Continue task synchronization from the core-returned task result for task-bound operations; taskless operations skip task verification and platform synchronization.
+
+When the task has an associated Issue or PR, follow `reference/issue-metadata-sync.md`, `reference/pr-summary-sync.md`, and the platform rules. The commit path passes `--result no_op` to summary-sync because it only synchronizes an existing PR identity. Synchronization failures are warnings and do not roll back the local commit.
 
 After task-bound finalization, run:
 
@@ -76,7 +96,7 @@ Do not claim task finalization without fresh verification output.
 
 ## 6. Render the next step
 
-Read `.agents/rules/next-step-output.md` immediately before calling the single next-step helper. A failed push keeps the task active and reports diagnostics; a final commit routes to `create-pr` or `complete-task` according to `prFlow`.
+Before rendering the next step, read `.agents/rules/next-step-output.md` and call the unified helper exactly once based on the latest task and PR state. A failed push keeps the task active and reports only diagnostics; a final commit routes to `create-pr` or `complete-task` according to `prFlow`.
 
 ## Notes
 

package/templates/.agents/skills/commit/SKILL.zh-CN.md

@@ -15,13 +15,13 @@ commit core 只返回一个主结果：`committed`、`no_op`、`committed_with_w
 
 ## 任务上下文
 
-入口允许省略 task ref，也接受旧位置 task ref 或 `--task <ref>` / `-t <ref>`。先调用 `agent-infra-internal task-context resolve {task-scope}`。
+入口可省略 task ref；显式 task scope 仅接受 `--task <ref>` 或 `-t <ref>`，不再解释位置 task ref。先调用 `agent-infra-internal task-context resolve {task-scope}`。
 
 - 显式 task scope 解析失败时停止。
 - 未显式指定 task scope 时，只有 `TASK_CONTEXT_NOT_FOUND` 可进入 taskless direct；detached HEAD、损坏候选或多匹配必须 fail closed。
-- 入口业务操作数包含字面 `--orchestrated` 时使用 `mode=orchestrated`，否则使用 `mode=direct`；不得从 run 文件或环境推断模式。
+- 入口业务操作数包含字面 `--orchestrated` 时直接失败并返回 `ORCHESTRATED_COMMIT_REMOVED`；普通入口使用 `mode=direct`，不得从 run 文件或环境推断模式。
 - taskless direct 不读取、创建或完成 task intent、receipt、checkpoint 或 task.md 收尾记录。
-- task-bound direct 不要求 delegation receipt；orchestrated 必须由 core 验证匹配的 activated commit receipt 和 capability。
+- task-bound direct 不要求 delegation receipt；local checkpoint 由 `code-task` 直接调用共享 core，独立 `commit` 继续使用 push delivery。
 - 解析成功后只使用 core 返回的 `taskId`；不得从环境、分支或文件名猜测任务身份。
 
 ## 1. 检查本地修改
@@ -47,7 +47,7 @@ git diff
 
 执行本步骤前读取 `reference/commit-orchestration.md`。
 
-将 message、明确 paths、expected HEAD/tree、task scope、agent、mode 和可选 push policy 写入临时 JSON，然后调用：
+将 message、明确 paths、expected HEAD/tree、task scope、agent、mode 和必填 push policy 写入临时 JSON，然后调用：
 
 ```bash
 agent-infra-internal git-workflow commit --input {commit-operation.json}
@@ -66,13 +66,12 @@ agent-infra-internal git-workflow commit --input {commit-operation.json}
   "expectedTree": "{TREE}",
   "push": {
     "remote": "origin",
-    "refs": ["refs/heads/{branch}"],
-    "automatic": true
+    "refs": ["refs/heads/{branch}"]
   }
 }
 ```
 
-taskless direct 省略 `taskRef`；orchestrated 必须显式传 `taskRef`、`agent` 和 `mode: "orchestrated"`。core 统一负责 repository/worktree mutation lock、task lock（仅 task-bound）、路径和敏感文件、staged scope、HEAD/tree、branch/ref、commit、push、保护分支、warning 和幂等校验。
+taskless direct 省略 `taskRef`；direct task-bound commit 使用 push delivery。core 统一负责 repository/worktree mutation lock、task lock（仅 task-bound）、路径和敏感文件、staged scope、HEAD/tree、branch/ref、commit、push、保护分支、warning 和幂等校验。
 
 - 有明确修改时最多创建一个本地 commit。
 - 无修改但需要交付本地领先的 HEAD 时只执行 push-only，不创建空 commit。

package/templates/.agents/skills/commit/config/verify.json

@@ -18,7 +18,7 @@
       "expected_action_pattern": "Commit"
     },
     "platform-sync": {
-      "when": "pr_number_exists",
+      "when": "pr_fact_bound",
       "expected_pr_comment_marker": "<!-- sync-pr:{task-id}:summary -->",
       "verify_in_labels_computed": true,
       "verify_pr_comment_last_commit_matches_head": true,

package/templates/.agents/skills/commit/reference/commit-orchestration.en.md

@@ -5,17 +5,17 @@ Commit, push, result mapping, and task finalization use one `commit-operation.ex
 ## Entry modes
 
 - `mode=direct`: explicit user invocation is the authorization. Task-bound direct may read task facts but does not require a delegation receipt; taskless direct is allowed only for `TASK_CONTEXT_NOT_FOUND` and skips task facts, review, task lock, checkpoint, and task.md finalization.
-- `mode=orchestrated`: an explicit task is required. Before the first Git write, the core validates the matching activated commit receipt, agent, stage, round, artifact, role, and unconsumed capability. Missing evidence returns `blocked` without writing Git.
+- `mode=orchestrated` is removed: standalone commit is no longer a lifecycle delegation stage. This mode returns `ORCHESTRATED_COMMIT_REMOVED` without writing Git; the code stage closes through a local checkpoint.
 
 ## Shared order
 
 1. Acquire the repository/worktree mutation lock; task-bound execution also acquires the task lock.
 2. Validate the repository, current branch, explicit paths, sensitive paths, staged scope, expected HEAD/tree, remote, and full heads ref.
-3. Validate the authorization for the selected mode.
+3. Validate direct-mode authorization.
 4. Create at most one local commit; with no changes, allow push-only and never create an empty commit.
 5. Return `COMMIT_AUTOPUSH_PROTECTED_BRANCH` on protected automatic push, or `COMMIT_PUSH_FAILED` on ordinary push failure, while retaining local facts.
 6. Return one primary result: `committed`, `no_op`, `committed_with_warnings`, `failed`, or `blocked`.
 
 ## Retry boundary
 
-Retries reread current HEAD, worktree, branch, and remote facts. A local commit that already exists is push-only and cannot produce a second commit. Taskless retries create no task record. Orchestration owns stage completion, sealing, and consumption of receipts; direct mode never fabricates them.
+Retries reread current HEAD, worktree, branch, and remote facts. A local commit that already exists is push-only and cannot produce a second commit. Taskless retries create no task record. Orchestration owns stage completion, sealing, and consumption of receipts; direct commits never fabricate them.

package/templates/.agents/skills/commit/reference/commit-orchestration.zh-CN.md

@@ -5,17 +5,17 @@ commit、push、结果映射和任务收尾使用同一个 `commit-operation.exe
 ## 入口模式
 
 - `mode=direct`：用户显式调用授权。task-bound direct 可读取 task facts，但不要求 delegation receipt；taskless direct 只在 `TASK_CONTEXT_NOT_FOUND` 时允许，并跳过 task facts、review、task lock、checkpoint 和 task.md 收尾。
-- `mode=orchestrated`：必须绑定明确 task，且 core 在第一个 Git 写入前验证匹配的 activated commit receipt、agent、stage、round、artifact、role 和未消费 capability。缺少任一项都返回 `blocked`，不写 Git。
+- `mode=orchestrated` 已移除：独立 commit 不再是生命周期 delegation stage；调用该模式返回 `ORCHESTRATED_COMMIT_REMOVED`，不写 Git。生命周期 code 阶段完成后由 local checkpoint 直接收口。
 
 ## 共享执行顺序
 
 1. 获取 repository/worktree mutation lock；task-bound 额外获取 task lock。
 2. 验证 repository、当前 branch、明确 paths、敏感路径、staged scope、expected HEAD/tree、remote 和 full heads ref。
-3. 完成模式对应的授权校验。
+3. 完成 direct 模式授权校验。
 4. 最多创建一个本地 commit；无修改时只允许 push-only，不创建空 commit。
 5. `main` / `master` 自动 push 返回 `COMMIT_AUTOPUSH_PROTECTED_BRANCH` warning；普通 push 失败返回 `COMMIT_PUSH_FAILED` warning，并保留本地事实。
 6. 返回唯一主结果：`committed`、`no_op`、`committed_with_warnings`、`failed` 或 `blocked`。
 
 ## 重试边界
 
-重跑重新读取当前 HEAD、worktree、branch 和 remote 事实。已有本地 commit 时只补 push，不创建第二个 commit；taskless 重跑不创建任何任务记录。orchestrated receipt 的 stage completion、seal 和 consume 由 orchestration core 负责，不由 direct 路径伪造。
+重跑重新读取当前 HEAD、worktree、branch 和 remote 事实。已有本地 commit 时只补 push，不创建第二个 commit；taskless 重跑不创建任何任务记录。生命周期 receipt 的 stage completion、seal 和 consume 由 orchestration core 负责；direct commit 不伪造生命周期 receipt。

package/templates/.agents/skills/commit/reference/pr-summary-sync.en.md

@@ -1,6 +1,6 @@
 # Commit-stage PR Summary Synchronization
 
-Run only when `{task-id}` is valid and task.md has a valid `pr_number`.
+Run only when `{task-id}` is valid and task.md has a `bound/verified` `pr_delivery_fact`.
 
 1. Run `agent-infra-internal platform-pr summary-context {task-id}`.
 2. Generate the plain summary body per `.agents/rules/pr-sync.md` and write it to a temporary file.

package/templates/.agents/skills/commit/reference/pr-summary-sync.zh-CN.md

@@ -1,6 +1,6 @@
 # Commit 阶段 PR 摘要同步
 
-仅当 `{task-id}` 有效且 `task.md` 存在有效 `pr_number` 时执行；否则跳过。
+仅当 `{task-id}` 有效且 `task.md` 存在 `bound/verified` 的 `pr_delivery_fact` 时执行；否则跳过。
 
 1. 调用 `agent-infra-internal platform-pr summary-context {task-id}` 获取 canonical 聚合输入。
 2. 按 `.agents/rules/pr-sync.md` 生成纯摘要正文并写入临时文件。

package/templates/.agents/skills/commit/reference/task-status-update.en.md

@@ -58,7 +58,7 @@ Prerequisites:
 - [ ] all code committed
 - [ ] all tests passed
 - [ ] code review approved
-- [ ] all workflow steps completed (for the `pr_tasks` list under each yaml `commit` step, decide whether to count them by the "PR path" rule: `prFlow=required` always counts; `prFlow=disabled` never counts; when absent, exclude only if `pr_status=skipped`, otherwise count)
+- [ ] all workflow steps completed (for the `pr_tasks` list under each yaml `commit` step, decide whether to count them by the "PR path" rule: `prFlow=required` always counts; `prFlow=disabled` never counts; when absent, exclude only if `pr_delivery_fact.state=skipped`, otherwise count)
 
 Required next-step commands (rendered by `prFlow`):
 
@@ -115,4 +115,4 @@ Next step - code review:
 {next-step-commands}
 ```
 
-> Note: beyond the cases above, if `task.md` contains a valid `pr_number`, the commit skill must sync the PR summary via `reference/pr-summary-sync.md` before entering the verification gate.
+> Note: beyond the cases above, if a verified bound `pr_delivery_fact` exists in `task.md`, the commit skill must sync the PR summary via `reference/pr-summary-sync.md` before entering the verification gate.

package/templates/.agents/skills/commit/reference/task-status-update.zh-CN.md

@@ -58,7 +58,7 @@ push 失败时保留任务 active 与本地 HEAD，只展示诊断和人工推
 - [ ] 所有代码都已提交
 - [ ] 所有测试通过
 - [ ] 代码审查已通过
-- [ ] 所有工作流步骤已完成（对 yaml `commit` 步骤的 `pr_tasks` 列表，按「走 PR 路径」判定是否计入：`prFlow=required` 始终计入；`prFlow=disabled` 不计入；缺省下仅当 `pr_status=skipped` 时不计入，否则计入）
+- [ ] 所有工作流步骤已完成（对 yaml `commit` 步骤的 `pr_tasks` 列表，按「走 PR 路径」判定是否计入：`prFlow=required` 始终计入；`prFlow=disabled` 不计入；缺省下仅当 `pr_delivery_fact.state=skipped` 时不计入，否则计入）
 
 必带下一步命令（按 `prFlow` 渲染）：
 
@@ -115,4 +115,4 @@ push 失败时保留任务 active 与本地 HEAD，只展示诊断和人工推
 {next-step-commands}
 ```
 
-> 注意：上述场景之外，只要 `task.md` 中存在有效 `pr_number`，commit 技能必须先按 `reference/pr-summary-sync.md` 同步 PR 摘要，再进入完成校验。
+> 注意：上述场景之外，只要 `task.md` 中存在 verified `pr_delivery_fact`，commit 技能必须先按 `reference/pr-summary-sync.md` 同步 PR 摘要，再进入完成校验。

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

@@ -7,7 +7,7 @@ description: >
 ---
 
 # Complete Manual Validation
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 
 ## Boundary / Critical Rules
@@ -15,6 +15,7 @@ description: >
 - This skill closes the manual-validation status in an existing PR summary comment; it does not create a parallel ordinary validation comment.
 - It must write `manual-validation.md` or `manual-validation-r{N}.md` so later PR summary refreshes can reuse the validation result.
 - If the `sync-pr` summary comment is missing, fail instead of creating a partial fallback summary.
+- Before generating manual-validation artifact Markdown that will be synced to an Issue, read `.agents/rules/sync-content-generation.md` and follow its generator-side constraints; Issue sync remains transparent and does not parse or rewrite the body.
 - After this skill runs, update `task.md` immediately.
 
 Version stamp rule: when creating or updating `task.md` frontmatter, read `.agents/rules/version-stamp.md` first and write or refresh `agent_infra_version`.
@@ -23,7 +24,7 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 After loading workflow / skill / rules instructions, and before any task-state judgment or user-visible conclusion, run the state check first. Reading instruction files does not count as an external-state action or conclusion.
 
-Run these commands and paste the raw output into both the user-facing reply and this round's `## State Check` section:
+Run these commands and paste the raw output into this round's `## State Check` section:
 
 ```bash
 agent-infra-internal task-snapshot {task-id} --format text
@@ -31,7 +32,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 ## Task Context Resolution
 
-> The entry point may omit the task ref and also accepts a legacy positional ref or `--task <ref>` / `-t <ref>`. Separate task scope from the full arguments while preserving every business operand, then call `agent-infra-internal task-context resolve {task-scope}` where `{task-scope}` is empty, one positional ref, or one task flag. Read only `taskId` from the structured result and bind `{task-id}` to that full `TASK-YYYYMMDD-HHMMSS` for downstream commands. Pass through resolution failures without scanning tasks locally.
+> The entry point may omit the task ref; explicit task scope accepts only `--task <ref>` or `-t <ref>`, and positional task refs are not interpreted. Preserve every other business operand, then call `agent-infra-internal task-context resolve {task-scope}` where `{task-scope}` is empty or one task flag. Read only `taskId` from the structured result and bind `{task-id}` to the full `TASK-YYYYMMDD-HHMMSS` for downstream commands. Pass through resolution failures without scanning tasks locally.
 
 > Resolve the task reference, then confirm that the task is in a state or directory supported by this skill and that `task.md` exists; if it cannot be located, handle it as a missing task and stop.
 
@@ -46,10 +47,10 @@ After resolving the artifact context and before this round's first artifact acti
 Input:
 
 ```text
-complete-manual-validation {task-ref} [{pr-ref}] {verification-summary}
+complete-manual-validation [--task <ref> | -t <ref>] [{pr-ref}] {verification-summary}
 ```
 
-- `{task-ref}` is required.
+- The task scope may be omitted; explicit scope accepts only `--task <ref>` or `-t <ref>`.
 - `{pr-ref}` is optional and accepts `#NN`, `NN`, or a full PR URL.
 - `{verification-summary}` is required. If it is missing, stop and ask for a validation summary; do not write an artifact or update the PR.
 
@@ -57,7 +58,7 @@ complete-manual-validation {task-ref} [{pr-ref}] {verification-summary}
 
 Check:
 - `.agents/workspace/active/{task-id}/task.md`
-- a valid PR: prefer explicit `{pr-ref}`, otherwise read `pr_number` from task.md frontmatter
+- a valid PR: prefer explicit `{pr-ref}`, otherwise read verified `pr_delivery_fact.identity.number` from task.md frontmatter
 
 Stop if the task is missing, the validation summary is missing, or no valid PR can be resolved.
 

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

@@ -7,7 +7,7 @@ description: >
 ---
 
 # 完成人工验证
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 
 ## 行为边界 / 关键规则
@@ -15,6 +15,7 @@ description: >
 - 本技能用于收尾已有 PR 摘要评论中的人工校验状态，不创建并行的普通验证留言。
 - 必须写入 `manual-validation.md` 或 `manual-validation-r{N}.md`，让后续 PR 摘要刷新可复用人工验证结果。
 - 找不到 `sync-pr` 摘要评论时失败，不创建部分摘要兜底。
+- 生成会同步到 Issue 的人工验证 artifact Markdown 前，先读取 `.agents/rules/sync-content-generation.md` 并遵循其中的生成端约束；Issue 同步保持透明，不解析或改写正文。
 - 执行本技能后必须立即更新 `task.md`。
 
 版本戳规则：创建或更新 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。
@@ -23,7 +24,7 @@ description: >
 
 在加载 workflow / skill / rules 指令之后、做任何任务状态判断或用户可见结论之前，必须先执行状态核对。指令类文件读取不算对外动作或结论。
 
-运行以下命令，并把原文粘贴到回复正文和本轮产物的 `## 状态核对` 段：
+运行以下命令，并把原文粘贴到本轮产物的 `## 状态核对` 段：
 
 ```bash
 agent-infra-internal task-snapshot {task-id} --format text
@@ -31,7 +32,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 ## 任务上下文解析
 
-> 入口允许省略 task ref，也接受旧位置 task ref 或 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空、位置 ref 或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
+> 入口可省略 task ref；显式 task scope 仅接受 `--task <ref>` 或 `-t <ref>`，不再解释位置 task ref。保留其余业务操作数后调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
 
 > 解析任务引用，并确认任务位于本技能支持的状态或目录且存在 `task.md`；无法定位时按未找到任务处理并停止。
 
@@ -46,10 +47,10 @@ agent-infra-internal task-snapshot {task-id} --format text
 输入格式：
 
 ```text
-complete-manual-validation {task-ref} [{pr-ref}] {verification-summary}
+complete-manual-validation [--task <ref> | -t <ref>] [{pr-ref}] {verification-summary}
 ```
 
-- `{task-ref}` 必填。
+- task scope 可省略；显式 scope 只接受 `--task <ref>` 或 `-t <ref>`。
 - `{pr-ref}` 可选，支持 `#NN`、`NN` 或完整 PR URL。
 - `{verification-summary}` 必填。若缺失，立即停止并提示补充验证说明；不写产物、不更新 PR。
 
@@ -57,7 +58,7 @@ complete-manual-validation {task-ref} [{pr-ref}] {verification-summary}
 
 检查：
 - `.agents/workspace/active/{task-id}/task.md`
-- 有效 PR：优先使用显式 `{pr-ref}`，否则读取 task.md frontmatter 的 `pr_number`
+- 有效 PR：优先使用显式 `{pr-ref}`，否则读取 task.md frontmatter 的 verified `pr_delivery_fact.identity.number`
 
 如果任务不存在、验证说明缺失，或无法解析有效 PR，立即停止。
 

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

@@ -34,7 +34,7 @@
       "stage_scope": ["analysis", "plan", "code"]
     },
     "platform-sync": {
-      "when": "pr_number_exists",
+      "when": "pr_fact_bound",
       "expected_pr_comment_marker_key": "prSummary",
       "expected_pr_comment_required_patterns": [
         "^### ✅ Manual Validation Passed$"

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

@@ -34,7 +34,7 @@
       "stage_scope": ["analysis", "plan", "code"]
     },
     "platform-sync": {
-      "when": "pr_number_exists",
+      "when": "pr_fact_bound",
       "expected_pr_comment_marker_key": "prSummary",
       "expected_pr_comment_required_patterns": [
         "^### ✅ 人工验证已通过$"

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

@@ -1,6 +1,6 @@
 # Manual-validation PR Summary Update
 
-Run only for a valid `{task-id}` whose task.md binds a `pr_number`; any user-supplied PR identity must match it.
+Run only for a valid `{task-id}` whose task.md binds a verified `pr_delivery_fact`; any user-supplied PR identity must match it.
 
 Follow `.agents/rules/pr-sync.md` for the shared summary structure and failure semantics.
 

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

@@ -1,6 +1,6 @@
 # PR 摘要人工验证更新
 
-人工验证产物结构见 `reference/report-template.md`。本步骤只在有效 `{task-id}` 且 task.md 已绑定 `pr_number` 时执行；用户另传 PR 身份时必须与绑定值一致。
+人工验证产物结构见 `reference/report-template.md`。本步骤只在有效 `{task-id}` 且 task.md 已绑定 verified `pr_delivery_fact` 时执行；用户另传 PR 身份时必须与 fact identity 一致。
 
 摘要结构与失败语义统一遵循 `.agents/rules/pr-sync.md`。
 

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

@@ -7,7 +7,7 @@ description: >
 ---
 
 # Complete Task
-> `--agent` values follow the "Collaborator Token Specification" in `.agents/rules/task-management.md`: standard AI short tokens (`claude`/`codex`/`antigravity`/`opencode`/`cursor`), long-name normalization (`claude-code`->`claude`, `antigravity-cli`->`antigravity`), or the `human` manual exception.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
 Host finalization uses receipt v2 with an immutable `receiptId`, monotonic `revision`, and canonical warnings. Lifecycle/identity/required-PR hard failures return `result: failed|blocked`; after lifecycle succeeds, comment, peripheral verification, and other sync failures return `result: completed_with_warnings` and six-field warnings, retrying only receipt-pending steps.
 
@@ -24,7 +24,7 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 After loading workflow / skill / rules instructions, and before any task-state judgment or user-visible conclusion, run the state check first. Reading instruction files does not count as an external-state action or conclusion.
 
-Run these commands and paste the raw output into both the user-facing reply and this round's `## State Check` section:
+Run these commands and paste the raw output into this round's `## State Check` section:
 
 ```bash
 agent-infra-internal task-snapshot {task-id} --format text
@@ -34,7 +34,7 @@ Before the state check is complete, do not make external-state assertions such a
 
 ## Task Context Resolution
 
-> The entry point may omit the task ref and also accepts a legacy positional ref or `--task <ref>` / `-t <ref>`. Separate task scope from the full arguments while preserving every business operand, then call `agent-infra-internal task-context resolve {task-scope}` where `{task-scope}` is empty, one positional ref, or one task flag. Read only `taskId` from the structured result and bind `{task-id}` to that full `TASK-YYYYMMDD-HHMMSS` for downstream commands. Pass through resolution failures without scanning tasks locally.
+> The entry point may omit the task ref; explicit task scope accepts only `--task <ref>` or `-t <ref>`, and positional task refs are not interpreted. Preserve every other business operand, then call `agent-infra-internal task-context resolve {task-scope}` where `{task-scope}` is empty or one task flag. Read only `taskId` from the structured result and bind `{task-id}` to the full `TASK-YYYYMMDD-HHMMSS` for downstream commands. Pass through resolution failures without scanning tasks locally.
 
 > Resolve the task reference, then confirm that the task is in a state or directory supported by this skill and that `task.md` exists; if it cannot be located, handle it as a missing task and stop.
 
@@ -66,27 +66,27 @@ agent-infra-internal platform-pr resolve-external {task-id} --agent {standard-ag
 ```
 
 - `mode=external`: only this invocation's typed `authorization` and `selected` fields authorize and identify external delivery; continue through the required-PR, local lifecycle, and terminal checks, while peripheral evidence failures become warnings after lifecycle.
-- `mode=normal`: use the existing local lifecycle prerequisites; historical `pr_number` / `pr_status` values do not authorize external delivery.
+- `mode=normal`: use the existing local lifecycle prerequisites; historical legacy PR fields do not authorize external delivery.
 - `status=failed|blocked`: stop immediately and show the stable error; `--force` cannot bypass it.
 
-**Gate read (project-level PR flow policy)**: Before running this step, read `.agents/.airc.json`'s `prFlow` field (three states: field absent = recommend PR by default, skipping allowed; `"required"` = PR mandatory; `"disabled"` = no PR flow), and `pr_status` from `task.md` frontmatter (`pending` / `created` / `skipped`).
+**Gate read (project-level PR flow policy)**: Before running this step, read `.agents/.airc.json`'s `prFlow` field (three states: field absent = recommend PR by default, skipping allowed; `"required"` = PR mandatory; `"disabled"` = no PR flow), and `pr_delivery_fact` from `task.md` frontmatter (`unbound` / `bound` / `skipped`).
 
-**PR dimension decision (evaluate the `prFlow` strong constraint FIRST, then `pr_status`)**:
+**PR dimension decision (evaluate the `prFlow` strong constraint FIRST, then `pr_delivery_fact.state`)**:
 
-| `prFlow` | `pr_status` | Decision |
+| `prFlow` | `pr_delivery_fact.state` | Decision |
 |---|---|---|
 | `disabled` | any | No PR path -> PR dimension satisfied, continue with the other prerequisites |
-| `required` | `created` | PR dimension satisfied, continue |
-| `required` | `pending` / `skipped` | **Stop**: under a mandatory PR flow you must run `/create-pr` first; `--skip-pr` is NOT accepted (including a pre-existing / manually-set `skipped`) |
-| absent | `created` / `skipped` | PR dimension satisfied, continue |
-| absent | `pending` | **Stop by default** and print the two-option guidance below; unless the user passes `--skip-pr` (writes `pr_status: skipped`, then continues) or `--force` |
+| `required` | `bound` | PR dimension satisfied, continue |
+| `required` | `unbound` / `skipped` | **Stop**: under a mandatory PR flow you must run `/create-pr` first; `--skip-pr` is NOT accepted (including a pre-existing / manually-set `skipped`) |
+| absent | `bound` / `skipped` | PR dimension satisfied, continue |
+| absent | `unbound` | **Stop by default** and print the two-option guidance below; unless the user passes `--skip-pr` (writes `pr_delivery_fact.state=skipped` through the current `platform-pr skip` writer, then continues) or `--force` |
 
-- `--skip-pr` handling: effective only when `prFlow` is not `required` -> set `pr_status` to `skipped` in `task.md`, then continue; when `prFlow=required`, ignore `--skip-pr` and stop per the table.
+- `--skip-pr` handling: effective only when `prFlow` is not `required` -> write `pr_delivery_fact.state=skipped` through the current `platform-pr skip` writer, then continue; when `prFlow=required`, ignore `--skip-pr` and stop per the table.
 - Note: `--force` may override the other prerequisites below, but does **NOT** lift the `prFlow=required` PR constraint (the only exit from the strong constraint is creating a PR).
 
 Two-option guidance for absent + `pending`:
 ```
-Task {task-id} has no PR yet (pr_status: pending). Choose one:
+Task {task-id} has no PR delivery decision yet (pr_delivery_fact: unbound). Choose one:
   - Go through the PR flow: /create-pr {task-ref}
   - Explicitly skip and complete: /complete-task {task-ref} --skip-pr
 ```

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

@@ -7,7 +7,7 @@ description: >
 ---
 
 # 完成任务
-> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」：标准 AI 短名（`claude`/`codex`/`antigravity`/`opencode`/`cursor`）、长名归一化（`claude-code`→`claude`、`antigravity-cli`→`antigravity`）或人工例外 `human`。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 宿主 finalization 使用 receipt v2（不可变 `receiptId`、单调 `revision` 和 canonical warnings）。生命周期/身份/required PR 等硬失败返回 `result: failed|blocked`；生命周期完成后，评论、外围验证和其他同步失败返回 `result: completed_with_warnings` 及六字段 warning，并仅重试 receipt 中的 pending step。
 
@@ -24,7 +24,7 @@ description: >
 
 在加载 workflow / skill / rules 指令之后、做任何任务状态判断或用户可见结论之前，必须先执行状态核对。指令类文件读取不算对外动作或结论。
 
-运行以下命令，并把原文粘贴到回复正文和本轮产物的 `## 状态核对` 段：
+运行以下命令，并把原文粘贴到本轮产物的 `## 状态核对` 段：
 
 ```bash
 agent-infra-internal task-snapshot {task-id} --format text
@@ -34,7 +34,7 @@ agent-infra-internal task-snapshot {task-id} --format text
 
 ## 任务上下文解析
 
-> 入口允许省略 task ref，也接受旧位置 task ref 或 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空、位置 ref 或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
+> 入口可省略 task ref；显式 task scope 仅接受 `--task <ref>` 或 `-t <ref>`，不再解释位置 task ref。保留其余业务操作数后调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
 
 > 解析任务引用，并确认任务位于本技能支持的状态或目录且存在 `task.md`；无法定位时按未找到任务处理并停止。
 
@@ -65,27 +65,27 @@ agent-infra-internal platform-pr resolve-external {task-id} --agent {standard-ag
 ```
 
 - `mode=external`：只以本次 typed result 的 `authorization` 和 `selected` 作为外部交付授权与绑定身份，继续 required-PR、本地生命周期和终态校验；外围证据失败在 lifecycle 后记录为 warning。
-- `mode=normal`：走现有本地生命周期前置条件；历史 `pr_number` / `pr_status` 不构成外部授权。
+- `mode=normal`：走现有本地生命周期前置条件；历史 PR 字段不构成外部授权。
 - `status=failed|blocked`：立即停止并展示稳定错误；`--force` 不得绕过。
 
-**门控读取（项目级 PR 流程策略）**：在执行本步骤前，读取 `.agents/.airc.json` 的 `prFlow` 字段（三态：字段缺省 = 默认推荐 PR、允许跳过；`"required"` = 强制 PR；`"disabled"` = 强制无 PR），以及 `task.md` frontmatter 的 `pr_status`（`pending` / `created` / `skipped`）。
+**门控读取（项目级 PR 流程策略）**：在执行本步骤前，读取 `.agents/.airc.json` 的 `prFlow` 字段（三态：字段缺省 = 默认推荐 PR、允许跳过；`"required"` = 强制 PR；`"disabled"` = 强制无 PR），以及 `task.md` frontmatter 的 `pr_delivery_fact`（`unbound` / `bound` / `skipped`）。
 
-**PR 维度判定（先判 `prFlow` 强约束，后看 `pr_status`）**：
+**PR 维度判定（先判 `prFlow` 强约束，后看 `pr_delivery_fact.state`）**：
 
-| `prFlow` | `pr_status` | 判定 |
+| `prFlow` | `pr_delivery_fact.state` | 判定 |
 |---|---|---|
 | `disabled` | 任意 | 无 PR 路径 → PR 维度满足，继续其余前置条件 |
-| `required` | `created` | PR 维度满足，继续 |
-| `required` | `pending` / `skipped` | **停止**：强制 PR 下必须先 `/create-pr`；`--skip-pr` 不被接受（含既有/手动写入的 `skipped`） |
-| 缺省 | `created` / `skipped` | PR 维度满足，继续 |
-| 缺省 | `pending` | **默认停止**并输出下方二选一引导；除非用户提供 `--skip-pr`（写 `pr_status: skipped` 后继续）或 `--force` |
+| `required` | `bound` | PR 维度满足，继续 |
+| `required` | `unbound` / `skipped` | **停止**：强制 PR 下必须先 `/create-pr`；`--skip-pr` 不被接受（含既有/手动写入的 `skipped`） |
+| 缺省 | `bound` / `skipped` | PR 维度满足，继续 |
+| 缺省 | `unbound` | **默认停止**并输出下方二选一引导；除非用户提供 `--skip-pr`（通过当前 `platform-pr skip` 写入器写入 `pr_delivery_fact.state=skipped` 后继续）或 `--force` |
 
-- `--skip-pr` 处理：仅在 `prFlow` 非 `required` 时生效——把 `task.md` 的 `pr_status` 写为 `skipped` 后继续；`prFlow=required` 时忽略 `--skip-pr` 并按上表停止。
+- `--skip-pr` 处理：仅在 `prFlow` 非 `required` 时生效——通过当前 `platform-pr skip` 写入器把 `task.md` 的 `pr_delivery_fact.state` 写为 `skipped` 后继续；`prFlow=required` 时忽略 `--skip-pr` 并按上表停止。
 - 注：`--force` 可越过下方其余前置条件，但**不解除 `prFlow=required` 的 PR 强约束**（强约束的唯一出口是创建 PR）。
 
 缺省 + `pending` 的二选一引导消息：
 ```
-任务 {task-id} 尚未创建 PR（pr_status: pending）。请二选一：
+任务 {task-id} 尚未决定 PR 交付（pr_delivery_fact: unbound）。请二选一：
   - 走 PR 流程：/create-pr {task-ref}
   - 显式跳过并完成：/complete-task {task-ref} --skip-pr
 ```