@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/templates/.agents/rules/issue-sync.zh-CN.md

@@ -1,8 +1,10 @@
-# Issue 同步
+# Issue 同步规则
+
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
 ## Marker 注册表
 
-以下隐藏标记是 Issue 同步的唯一权威注册表：
+以下 key 及格式是 Issue 评论身份的兼容契约；调用方只传 key/资源，不自行拼 marker。
 
 | Key | Marker |
 |---|---|
@@ -12,8 +14,63 @@
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
 
-Skill 正文应引用 marker key，具体 marker 字符串只保留在本规则或平台适配器默认值中。
+`prSummary` 属于 `.agents/rules/pr-sync.md`，本规则不实现 PR 聚合。
+
+`pr-review` 原文只通过 `artifact` / `artifactChunk` marker 同步为 Issue artifact 评论，不作为 `restore-task` 恢复来源；恢复仍只接受 Issue 编号并只读注册的 Issue marker，不新增 PR 来源。
+
+## 平台 intent
+
+平台 upstream、认证、capability、分页、marker 查找、幂等 create/update、分片、重试与错误分类由 typed platform core 统一处理：
+
+```bash
+agent-infra-internal platform-context resolve [--cwd <path>]
+agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
+agent-infra-internal platform-comment owner <task-ref>
+agent-infra-internal platform-comment sync <task-ref> \
+  --kind task|artifact|summary|cancel --agent {standard-agent-token} \
+  [--artifact <canonical.md>] [--body-file <path|->] [--backfill]
+```
+
+- `applied|no-op|degraded` → exit 0；`failed` → exit 1；`blocked` → exit 2。
+- task 评论保持 `<details>` frontmatter 可逆格式；artifact 原文内联并在超过 profile 上限时使用 `artifactChunk`。
+- 相同 intent 重放必须收敛为 `no-op`；重复 marker 返回 `COMMENT_MARKER_CONFLICT` 且不写入。
+- 外部贡献者锁定统一使用 `platform-comment owner`；不同作者且无 triage 时返回 `COMMENT_OWNER_CONFLICT`。
+
+## 降级与告警
+
+平台结果不直接写 task.md。调用方在有关联任务时把关键失败映射为 workflow warning：
+
+- capability 不足：`IMPORTANT / PERMISSION_DEGRADED`
+- 评论同步永久失败：`ACTION_REQUIRED / COMMENT_SYNC_FAILED`
+- 网络重试耗尽：`ACTION_REQUIRED / NETWORK_RETRY_EXHAUSTED`
+
+使用 `agent-infra-internal task-warning {task-id} add ...` 登记；不得手写 warning 表。
+
+```bash
+agent-infra-internal task-warning {task-id} add \
+  --step issue-sync --severity {severity} --code {code} \
+  --target {target} --message {message} --action {action}
+```
+
+## Issue 元数据 intent
+
+所有 Issue 元数据写入统一使用：
+
+```bash
+agent-infra-internal platform-issue inspect {task-id}
+agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
+agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {standard-agent-token}
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} {desired-state-flags}
+```
+
+`sync` 支持 status/in labels、assignee、milestone、Issue Type、pinned fields、需求复选框与 Issue state。省略 flag 表示 preserve，`none` 表示显式清空。适配层统一处理集合差集、动态 schema、权限降级、dry-run、重试、错误分类与幂等重放；SKILL 不得拼装平台 CLI、GraphQL 或权限分支。
+
+- `planned|applied|no-op|degraded` → exit 0
+- `failed` → exit 1
+- `blocked` → exit 2
+
+status labels 始终至多一个；关闭后不保留 status label。`in:` labels 只从项目允许映射与仓库实际 labels 交集产生。需求复选框以 task.md 原文为身份，歧义时 fail closed。
 
-当前代码平台未提供 Issue 适配器；`platform-issue` 返回结构化 no-op/degraded operations。
+## 补发
 
-自定义平台会跳过 Issue 元数据、标签、里程碑、负责人和评论同步，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和平台适配器。请继续正常写入本地任务产物。
+complete-task 按 artifact catalog 时间线遍历本地已有产物：task 使用 `--kind task`，其余使用 `--kind artifact --artifact <file> --backfill`；最后用 `--kind summary --body-file <path>` 原地同步交付摘要。artifact backfill 在远端缺少 marker 时创建带“历史产物补发”提示的评论；已存在合法 marker 集合时保持原评论和分片不变并返回 `no-op`；marker 冲突仍失败。该判定由 core 完成，不由 Skill 扫描评论或拼标题。

package/templates/.agents/rules/label-milestone-setup.en.md

@@ -1,5 +1,18 @@
 # Label and Milestone Setup
 
-This code platform does not provide built-in label or milestone setup.
+Read this rule before initializing labels or milestones, or before changing milestone metadata during release work.
 
-Initialization of remote labels and milestones is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and scripts. Local task workflow files remain usable without remote metadata setup.
+## Entry points
+
+Use the shared scripts rather than composing provider commands in a skill:
+
+```text
+bash .agents/skills/init-labels/scripts/init-labels.sh [--cleanup-stale-in]
+bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
+```
+
+`init-labels.sh` reads the repository's `labels.in` configuration, creates or updates the declared `in:` labels, and preserves unrelated labels. `--cleanup-stale-in` is destructive and may only be passed after explicit confirmation; it removes stale `in:` labels that are no longer declared.
+
+`init-milestones.sh` owns milestone inference and the provider-specific write path. Callers must pass the requested arguments through unchanged and must not rebuild milestone discovery, ordering, branch ancestry, or write logic.
+
+Both scripts return a stable status. A successful no-op is still success; a degraded result must be reported without claiming that remote metadata was changed. Failed or cancelled operations must not be reported as completed.

package/templates/.agents/rules/label-milestone-setup.zh-CN.md

@@ -1,5 +1,18 @@
 # Label 和 Milestone 初始化
 
-当前代码平台未内置标签或里程碑初始化支持。
+在初始化 label、milestone，或在发布工作中修改 milestone 元数据前，先阅读本规则。
 
-自定义平台会跳过远端标签和里程碑初始化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和脚本。即使没有远端元数据初始化，本地任务工作流文件仍可使用。
+## 入口
+
+SKILL 应调用共享脚本，不得自行拼装 provider 命令：
+
+```text
+bash .agents/skills/init-labels/scripts/init-labels.sh [--cleanup-stale-in]
+bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
+```
+
+`init-labels.sh` 读取仓库的 `labels.in` 配置，创建或更新声明的 `in:` label，并保留无关 label。`--cleanup-stale-in` 具有破坏性，只有在得到明确确认后才能传入；它会删除不再声明的过期 `in:` label。
+
+`init-milestones.sh` 负责 milestone 推断和 provider 写入路径。调用方应原样传递请求参数，不得重新实现 milestone 发现、排序、分支祖先判断或写入逻辑。
+
+两个脚本都返回稳定状态。成功的 no-op 仍算成功；degraded 结果必须如实报告，不能声称远端元数据已变更。失败或取消的操作不得报告为已完成。

package/templates/.agents/rules/local-artifact-repair.en.md

@@ -0,0 +1,46 @@
+# General Rule - Model-Driven Local Artifact Repair
+
+This rule applies only when `review-analysis`, `review-plan`, or `review-code` handles a finalizer failure for **the same controlled review artifact**. It does not apply to `task.md`, the ledger, receipts, source code, Git, platform resources, or lifecycle state.
+
+## Authorization Boundary
+
+- The finalizer only reads facts, validates state, normalizes successful results, and performs atomic writes. It does not maintain a recoverable-error allowlist, infer repairability, or choose report content to delete.
+- The initial finalizer call is not counted as a repair attempt. Editing is allowed only after the mechanical safety gates pass and the model explicitly determines that the current problem can be solved by a minimal, explainable artifact change.
+- The model may edit only the one ordinary review artifact declared by the current review skill, and the file must be inside the current task directory. It must not edit `task.md`, the review disagreement ledger, receipts, source code, other reports, or remote resources.
+- `changed=false`, an error code, or a format shape is diagnostic evidence, not automatic authorization. The model must judge each case using the complete diagnostic, artifact content, and context.
+
+## Non-bypassable Mechanical Safety Gates
+
+Before every model edit, confirm that:
+
+1. the finalizer returned a failure and no artifact operation was committed;
+2. the task, stage, artifact, review round, identity, and provenance still match;
+3. the target is an ordinary file inside the current task directory, with no concurrency conflict, permission error, I/O uncertainty, or target replacement;
+4. the change does not alter human-decision semantics, decision-detail or ledger identity, and does not involve task state, receipts, Git, platform, or any other external side effect. A known and verifiable pending human decision may remain when the model proves the edit is unrelated to that decision.
+
+If any condition fails, stop immediately without invoking a model edit. The model cannot bypass these gates.
+
+## Dynamic Convergence Loop
+
+1. Run the initial finalizer with the fixed task, stage, artifact, and orchestrated intent.
+2. On success, use that complete result for the existing completion gates; do not rescan the ledger or write summary fields manually.
+3. On failure with the safety gates passed, let the model read the structured diagnostic, current artifact, and required context, then decide whether to repair or stop. It must explain the scope and reason for the proposed change.
+4. If the model continues, perform one minimal edit to the artifact. Increment `repairAttempts` only when the file bytes actually change, then rerun the same finalizer intent completely.
+5. Re-run every safety check after each retry. A new, independent problem still limited to the same artifact may be offered to the model for another decision; the previous repairability decision must not be reused automatically.
+6. Stop immediately when the model cannot establish safety or identifies an environment, permission, concurrency, identity, provenance, unknown-state, uncertain human-decision semantics/details, or other non-local problem. A known human decision is not itself a stop condition.
+7. Stop when the diagnostic or artifact fingerprint repeats, no byte-level progress occurs, or the model cannot propose a verifiable minimal change.
+8. Allow at most 8 actual artifact edits per skill invocation as an emergency circuit breaker. This cap only prevents infinite loops and resource exhaustion; it is not a normal business stop condition and does not mean that at most eight problems may be repaired. Preserve the final structured diagnostic when the cap is reached.
+
+The repair count exists only in the in-memory context of the current skill invocation. Do not write it to `task.md`, the ledger, or a public receipt. Do not create different normal budgets by error code, skill, or problem type.
+
+## Completion Events and User Output
+
+- After the final complete finalizer result succeeds, publish the review completed event using that same result's provenance, ledger state, verdict, and counts. Generate cross-stage next-step commands only when `stageStatus.canAdvance=true` and the verdict is Approved; when `canAdvance=false`, still record the result and route to same-stage revision/review.
+- On failure, model stop, lack of progress, repeated diagnostics, or the emergency cap, do not publish a completed event, advance the lifecycle, generate cross-stage commands, or fabricate an approval.
+- Stopping advancement does not discard review results. User output must show the artifact path, the last safely readable summary/findings, actual `repairAttempts`, the last structured diagnostic, and the stop reason.
+- If the summary cannot be safely parsed, show only the artifact path and the raw structured diagnostic; do not infer counts or add a conclusion, and state that lifecycle advancement stopped while the artifact remains available.
+- A stop path may only suggest rerunning the current review skill or handling the issue manually. It must not invoke cross-stage helpers such as `code-task` or `complete-task`.
+
+## Lifecycle Isolation
+
+`complete-task`, alert closing, task restoration, and other task-lifecycle/task-finalization entry points involve task state, receipts, remote results, or archival side effects and do not consume this rule. They retain their own hard-stop, same-intent retry, and unknown-state semantics.

package/templates/.agents/rules/local-artifact-repair.zh-CN.md

@@ -0,0 +1,46 @@
+# 通用规则 - 模型驱动的本地产物修复
+
+本规则只适用于 `review-analysis`、`review-plan`、`review-code` 在 finalizer 失败后处理**同一个受控 review artifact** 的场景。它不适用于 task.md、账本、receipt、源码、Git、平台资源或生命周期状态。
+
+## 授权边界
+
+- finalizer 只负责读取事实、校验状态、规范化成功结果和原子写入；它不维护可修复错误码白名单，不推断 repairability，也不自动选择要删除的报告内容。
+- 首次 finalizer 调用不计入修复次数。只有在机械安全门通过后，模型明确判断当前问题能通过最小、可解释的 artifact 修改解决时，才允许编辑。
+- 模型只能修改当前 review skill 声明的一个普通 review artifact，且该文件必须位于当前 task 目录。不得修改 task.md、审查分歧账本、receipt、源码、其他报告或远端资源。
+- `changed=false`、错误码或某个格式形状只是诊断事实，不是自动批准。模型必须结合完整诊断、artifact 内容和上下文逐例判断。
+
+## 不可绕过的机械安全门
+
+在每次模型编辑前确认：
+
+1. finalizer 返回失败，且没有已提交的 artifact operation；
+2. 任务、stage、artifact、review round、身份和 provenance 仍然一致；
+3. 目标是当前 task 目录内的普通文件，没有并发冲突、权限错误、I/O 不确定性或目标被替换；
+4. 不改变人工裁决语义、裁决详情或账本身份，也不涉及任务状态、receipt、Git、平台或其他外部副作用；已知且可核验的 pending 人工裁决可以保留，但模型必须证明本次修改与该裁决无关。
+
+任一条件不满足，立即停止，不调用模型编辑。安全门不能被模型的语义判断绕过。
+
+## 动态收敛循环
+
+1. 使用固定的 task、stage、artifact 和 orchestrated intent 执行首次 finalizer。
+2. 成功时使用这一次完整结果进入既有完成前门禁；不得重新扫描账本或手工补写摘要。
+3. 失败且安全门通过时，模型读取结构化诊断、当前 artifact 和必要上下文，决定继续修复或停止，并说明修改范围和理由。
+4. 模型选择继续时，只做一次最小 artifact 编辑。只有文件字节实际发生变化，才增加一次 `repairAttempts`，然后完整重跑同一个 finalizer intent。
+5. 每次重跑都重新执行全部安全校验。修复后出现新的、独立且仍局限于该 artifact 的问题，可以再次交给模型判断；不能沿用上一次“可修复”的结论。
+6. 模型无法证明下一步安全，或判断问题属于环境、权限、并发、身份、provenance、状态未知、人工裁决语义/详情不确定或其他非本地问题时，立即停止。已知人工裁决本身不是停止条件。
+7. 诊断重复、artifact 指纹重复、没有实际字节进展或模型没有提出可验证的最小修改时，立即停止。
+8. 每次 skill invocation 最多允许 8 次实际 artifact 修改作为紧急熔断。该上限只防止死循环和资源失控，不是正常业务停止条件，也不表示最多只能修复 8 个问题。达到上限时保留最后结构化诊断并停止。
+
+修复次数只存在于当前 skill invocation 的内存上下文，不写入 task.md、ledger 或公共 receipt。不得按错误码、技能或问题类型设置不同的正常预算。
+
+## 完成事件与用户输出
+
+- 最终一次完整 finalizer 成功后，必须使用同一次返回的 provenance、账本状态、verdict 和计数发布 review completed 事件；`stageStatus.canAdvance=true` 且结论为 Approved 时才可生成跨阶段 next-step 命令，`canAdvance=false` 时仍须登记结果并路由到同阶段修订/复审。
+- 失败、模型停止、无进展、诊断重复或紧急熔断时，不发布 completed 事件，不推进生命周期，不生成跨阶段命令，也不伪造通过结论。
+- 停止推进不等于丢弃审查结果。用户输出必须展示 artifact 路径、已安全读取的最后有效 summary/findings、实际 `repairAttempts`、最后结构化诊断和停止原因。
+- summary 无法安全解析时，只展示 artifact 路径和原始结构化诊断，不推算计数、不补写结论，并明确生命周期推进已停止但产物仍可查看。
+- 停止路径只提示重新运行当前 review skill 或进行人工处理；不能调用 `code-task`、`complete-task` 等跨阶段 helper。
+
+## 生命周期隔离
+
+`complete-task`、告警关闭、恢复任务和其他 task-lifecycle/task-finalization 入口涉及任务状态、receipt、远端结果或归档副作用，不消费本规则。它们继续使用各自的硬失败、同一 intent 重试和状态未知语义。

package/templates/.agents/rules/milestone-inference.en.md

@@ -1,5 +1,15 @@
 # Milestone Inference
 
-This code platform does not provide milestone inference; `platform-issue sync --milestone ...` returns a structured no-op/degraded result.
+> `--agent` values are defined in `.agents/rules/task-management.md` under “Collaborator Token Specification”.
 
-Milestone narrowing and reuse are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates. Do not block task progress when no platform-specific milestone implementation is available.
+Milestones narrow through declarative Issue intents:
+
+```bash
+# create/import phase
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone initial
+
+# code phase
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone specific
+```
+
+`initial` prefers a valid task milestone, otherwise the lowest open `X.Y.x`, then `General Backlog`. `specific` narrows a release line to the highest open patch version using main/release-line ancestry. Missing facts or triage permission preserve the remote value and return skipped/degraded. `create-pr` reuses the Issue milestone in the 09/10 PR adapter.

package/templates/.agents/rules/milestone-inference.zh-CN.md

@@ -1,5 +1,27 @@
-# Milestone 推断
+# Milestone 推断规则
 
-当前代码平台未提供里程碑推断；`platform-issue sync --milestone ...` 返回结构化 no-op/degraded 结果。
+> `--agent` 取值见 `.agents/rules/task-management.md`「合作者 token 规范」。
 
-自定义平台会跳过里程碑收窄和复用逻辑，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。没有平台专属里程碑实现时，不要阻塞任务推进。
+Milestone 继续按生命周期逐步收窄，但候选读取、分支判断、权限降级和写入统一由 `platform-issue` 处理。
+
+## 阶段 1：创建或导入
+
+```bash
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone initial
+```
+
+优先使用 task.md 中存在且有效的显式 milestone；否则从 open milestones 选择最低 `X.Y.x` 版本线，最后回退 `General Backlog`。`triage=false` 或外部事实不足时保持远端值并返回 skipped/degraded。
+
+## 阶段 2：`code-task`
+
+```bash
+agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --milestone specific
+```
+
+版本线收窄规则保持不变：主干模式在当前版本线取最高 patch；多版本分支模式依据 release-line/main 祖先关系选择版本线。无法可靠判断时保持原值。完成门禁仍拒绝 `X.Y.x`。
+
+## 阶段 3：`create-pr`
+
+PR 只复用关联 Issue 的具体 milestone；该 PR 资源写入属于 09/10，不在 `platform-issue` 中实现。
+
+调用方不得重新实现 milestone 列表、排序、分支祖先或平台写入逻辑。

package/templates/.agents/rules/next-step-output.en.md

@@ -110,11 +110,11 @@ This section is a **third standalone rule, co-equal with the two above**, used o
   …(one entry per status=needs-human-decision row of this stage in task.md `## 审查分歧账本`)
 
 View details:
-  - All pending decisions: ai task decisions {task-ref}
-  - A single item's full background/options/impact/recommendation: ai task decisions {task-ref} <ordinal|ledger-id>
+  - All pending decisions: ai task decisions --task {task-ref}
+  - A single item's full background/options/impact/recommendation: ai task decisions --task {task-ref} --item <ordinal|ledger-id>
 
 To resolve:
-  - ai decide {task-ref} <ordinal|ledger-id> <decision and rationale>
+  - ai decide --task {task-ref} --item <ordinal|ledger-id> <decision and rationale>
 
 This command atomically creates the `HDR-N` ruling record, flips the target ledger row to `human-decided`, and updates evidence and the activity log; do not manually edit only part of the transaction.
 

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -110,11 +110,11 @@ Completed at: YYYY-MM-DD HH:mm:ss
   …（task.md `## 审查分歧账本` 中本阶段每个 status=needs-human-decision 行一条）
 
 查看详情：
-  - 全部待裁决项：ai task decisions {task-ref}
-  - 单项完整背景/选项/影响/建议：ai task decisions {task-ref} <序号|账本ID>
+  - 全部待裁决项：ai task decisions --task {task-ref}
+  - 单项完整背景/选项/影响/建议：ai task decisions --task {task-ref} --item <序号|账本ID>
 
 完成裁决：
-  - ai decide {task-ref} <序号|账本ID> <裁决内容与理由>
+  - ai decide --task {task-ref} --item <序号|账本ID> <裁决内容与理由>
 
 该命令原子写入 `HDR-N` 裁定记录、把目标账本行翻为 `human-decided`、更新 evidence 与活动日志；不要手工只修改其中一部分。
 

package/templates/.agents/rules/no-mid-flow-questions.en.md

@@ -85,7 +85,7 @@ Use these checks together:
 - **Small-impact exemption**: if it is only a local, reversible, low-cost execution detail, record it under `## Assumptions` instead of upgrading it to a human ruling.
 - **Fallback**: when unsure whether it is key, treat it as key; `review-*` must check whether the executor missed any `[needs-human-decision]` markings that should have been upgraded.
 
-> Use `ai task decisions <task-ref>` to view all pending decisions of a task and their detail blocks.
+> Use `ai task decisions [--task <ref> | -t <ref>]` to view all pending decisions of a task and their detail blocks.
 
 ## Human Review Checkpoint Semantics
 

package/templates/.agents/rules/no-mid-flow-questions.zh-CN.md

@@ -85,7 +85,7 @@
 - **小影响豁免**：若它只是局部、可逆、低成本的执行细节，写入 `## 假设` 即可，不升级为人工裁决。
 - **兜底**：无法判断是否关键时按关键处理；`review-*` 需要复核执行方是否漏标应升级的 `[needs-human-decision]`。
 
-> 用户可用 `ai task decisions <task-ref>` 查看某任务全部待裁决项及其详情块。
+> 用户可用 `ai task decisions [--task <ref> | -t <ref>]` 查看某任务全部待裁决项及其详情块。
 
 ## 人工审查检查点语义
 

package/templates/.agents/rules/pr-sync.en.md

@@ -1,31 +1,40 @@
 # PR Summary Synchronization
 
-> `--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”.
 
-The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, the marker, current HEAD, paginated comment lookup, and create/update/no-op reconciliation.
+The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, marker/HEAD wrapping, paginated comment lookup, and reconciliation.
 
-## Inputs
+## Three-Layer Isolation
 
-```bash
-agent-infra-internal platform-pr summary-context {task-id}
-```
-
-Use only the returned latest canonical `plan*`, `review-plan*`, `code*`, `review-code*`, and `manual-validation*` for lifecycle claims. The summary covers scope, tests, review history, and exactly one manual-validation state. It also includes a `### PR Code Changes` section based on authoritative base/head facts from `platform-pr inspect` and the complete `git diff --find-renames --numstat base...head`, with reconciled runtime, test, skill/rule, template, documentation, and other categories plus rename, mechanical-mirror, and unnecessary-change analysis.
-
-## Publish
+- `sync-pr:{task-id}:summary` (`platform-pr summary-sync`) is an updatable reviewer summary; it is neither a process copy nor a formal Review.
+- The full `pr-review*` process copy lives in the Issue artifact comment (`platform-comment sync --kind artifact`) and is restored by `restore-task` under its Issue-only contract.
+- A formal PR Review (`platform-pr-review publish`) is the only formal conclusion carrier published to the PR, bound to the reviewed head SHA, and includes conclusion, findings, receipt, and the Issue artifact link.
 
-Write only the summary body to a file, without marker or SHA:
+The three never cross: a regular PR comment does not carry the full process copy; an Issue artifact comment is not treated as a formal Review; a summary is not presented as a formal Review.
 
 ```bash
+agent-infra-internal platform-pr summary-context {task-id}
+
 agent-infra-internal platform-pr summary-sync {task-id} \
   --agent {standard-agent-token} --body-file {summary-body-file}
 ```
 
-The core wraps `<!-- sync-pr:{task-id}:summary -->` and current `<!-- last-commit: ... -->`, then creates, updates in place, or returns no-op. Duplicate markers fail deterministically. Callers never assemble shell/heredoc comment commands.
+Use only canonical inputs returned by the context command. Write the plain body without marker or SHA. The core owns `<!-- sync-pr:{task-id}:summary -->`, current `<!-- last-commit: ... -->`, create/update/no-op behavior, and duplicate-marker conflicts. Summary failure never rolls back a PR or commit.
 
-`create-pr` does not roll back the PR on summary failure; `commit` records a warning without rolling back; manual validation refreshes after its canonical artifact is written.
+The canonical comment envelope produced by the core is:
+
+```markdown
+<!-- sync-pr:{task-id}:summary -->
+<!-- last-commit: {git-head-sha} -->
+## Review Summary
+{manual-validation-section}
+### Key Technical Decisions
+### Review History
+### Test Results
+### PR Code Changes
+```
 
-For a linked task, the caller records a structured warning:
+Canonical inputs include `manual-validation.md`. The manual-validation section is one of `### ✅ Manual Validation Passed`, `### ⚠️ Manual Verification Required`, or `### ✅ No Manual Verification Needed`; `complete-manual-validation` refreshes the same summary in place. The PR code-change section uses authoritative base/head facts from `platform-pr inspect` and the complete `git diff --find-renames --numstat base...head`, reconciles runtime, test, skill/rule, template, documentation, and other categories, and explains renames, mechanical mirrors, and potentially unnecessary changes.
 
 ```bash
 agent-infra-internal task-warning {task-id} add --step {step} --severity WARNING \

package/templates/.agents/rules/pr-sync.zh-CN.md

@@ -1,16 +1,24 @@
 # PR 摘要同步
 
-> `--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 规范」。
 
 PR 摘要的语义聚合由模型完成；canonical 产物选择、marker、当前 HEAD、分页评论查找和 create/update/no-op 由 typed core 负责。
 
+## 三层隔离
+
+- `sync-pr:{task-id}:summary`（`platform-pr summary-sync`）是可更新的 reviewer 摘要，不是过程原文，也不是正式 Review。
+- `pr-review*` 完整过程原文在 Issue artifact 评论（`platform-comment sync --kind artifact`），由 `restore-task` 按 Issue-only 契约恢复。
+- 正式 PR Review（`platform-pr-review publish`）是唯一发布到 PR 的正式结论载体，绑定被审 head SHA，含结论、finding、receipt 与 Issue artifact 链接。
+
+三者不串用：PR 普通评论不承载完整过程原文；Issue artifact 评论不当作正式 Review；摘要不冒充正式 Review。
+
 ## 聚合输入
 
 ```bash
 agent-infra-internal platform-pr summary-context {task-id}
 ```
 
-只使用返回的 canonical latest `plan*`、`review-plan*`、`code*`、`review-code*`、`manual-validation*`。模型据此生成 reviewer 摘要正文，至少包含：
+只使用返回的 canonical latest `plan*`、`review-plan*`、`code*`、`review-code*`、`manual-validation*`（包括 `manual-validation.md`）。模型据此生成 reviewer 摘要正文，至少包含：
 
 - 变更摘要与实现范围
 - 测试结果
@@ -20,6 +28,19 @@ agent-infra-internal platform-pr summary-context {task-id}
 
 保留人工校验项时，每条写明校验内容、定位和只能人工完成的原因。
 
+core 最终包装出的 canonical 评论结构为：
+
+```markdown
+<!-- sync-pr:{task-id}:summary -->
+<!-- last-commit: {git-head-sha} -->
+## 审查摘要
+{manual-validation-section}
+### 关键技术决策
+### 审查历程
+### 测试结果
+### PR 代码增减
+```
+
 ## 发布
 
 把聚合后的纯正文写入 `{summary-body-file}`，不要自行添加 marker 或 commit SHA：

package/templates/.agents/rules/release-commands.en.md

@@ -1,5 +1,44 @@
-# Release Commands
+# Release Platform Commands
 
-This code platform does not provide a release-note adapter.
+Release-note platform operations use a typed internal intent. Callers consume structured JSON and do not interpret platform commands, raw fields, identity email rules, or authentication errors.
 
-Local `agent-infra-internal platform-release-notes stage --notes-file "{notes-file}"` still normalizes an external file and returns its digest. Use `context` to receive a structured `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op and do not probe another platform client. Publish with `--expected-sha256` remains a no-op until an adapter is provided.
+## Collect Release-note Context
+
+```bash
+agent-infra-internal platform-release-notes context \
+  --from-tag "v{prev-version}" \
+  --to-tag "v{version}" \
+  --branch "{branch}" \
+  --history-limit 3
+```
+
+The result contains `history`, `pullRequests`, `closingIssues`, and commit `authors` with normalized `login` / `resolution` values. `status: no-op` with error code `PLATFORM_RELEASE_NOTES_UNSUPPORTED` means the current platform does not support remote release-note operations.
+
+### Identity Safety Boundary
+
+- Render an identity as `@login` only when `resolution` is `platform-user` or `platform-noreply` and `login` is non-empty.
+- Exclude `resolution: unresolved` identities from the release-note contributor list. Never infer a login from a name, email address, domain, brand, or same-named platform account, and never substitute a guessed personal or organization account.
+- Do not publish unresolved identity emails or identity-verification TODOs in Release notes. Record any required investigation outside the release workflow without creating a platform mention.
+
+## Stage Release Notes
+
+```bash
+agent-infra-internal platform-release-notes stage \
+  --notes-file "{notes-file}"
+```
+
+The command accepts only an external regular file, normalizes it atomically, and returns SHA-256 for its exact bytes.
+
+## Publish Release Notes
+
+Call this only after user confirmation:
+
+```bash
+agent-infra-internal platform-release-notes publish \
+  --tag "v{version}" \
+  --title "v{version}" \
+  --notes-file "{notes-file}" \
+  --expected-sha256 "{preview-sha256}"
+```
+
+The command recomputes the digest before platform access and performs no platform write on mismatch. On a match it updates an existing Release or creates it when missing; `--dry-run` returns only the planned operation. Exit code `0` means success, `1` means a stable failure, and `2` means a network or platform block.

package/templates/.agents/rules/release-commands.zh-CN.md

@@ -1,5 +1,44 @@
-# Release 命令
+# Release 平台命令
 
-当前代码平台未提供发布说明 adapter。
+发布说明平台操作统一使用 typed internal intent。调用方只解释结构化 JSON，不解析平台命令、原始字段、身份邮箱规则或认证错误。
 
-本地 `agent-infra-internal platform-release-notes stage --notes-file "{notes-file}"` 仍可规范化工作树外文件并返回摘要。调用 `context` 会返回结构化的 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op，不得探测其他平台 client；提供 adapter 前，带 `--expected-sha256` 的 publish 同样保持 no-op。
+## 收集发布说明上下文
+
+```bash
+agent-infra-internal platform-release-notes context \
+  --from-tag "v{prev-version}" \
+  --to-tag "v{version}" \
+  --branch "{branch}" \
+  --history-limit 3
+```
+
+结果包含 `history`、`pullRequests`、`closingIssues` 和带规范化 `login` / `resolution` 的 commit `authors`。`status: no-op` 且错误码为 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` 表示当前平台不支持远端发布说明能力。
+
+### 身份安全边界
+
+- 只有 `resolution` 为 `platform-user` 或 `platform-noreply` 且 `login` 非空的身份可以渲染为 `@login`。
+- `resolution: unresolved` 的身份不得进入发布说明的贡献者列表；不得从 Name、邮箱、域名、品牌或同名平台账号推断 login，也不得替换成推测的个人或组织账号。
+- 不得把未解析身份的邮箱或身份确认 TODO 写入可发布的 Release notes。需要调查时仅在发布流程外记录，不得产生平台 mention。
+
+## Stage Release notes
+
+```bash
+agent-infra-internal platform-release-notes stage \
+  --notes-file "{notes-file}"
+```
+
+命令只接受工作树外普通文件，原子规范化并返回精确 bytes 的 SHA-256。
+
+## 发布 Release notes
+
+用户确认后调用：
+
+```bash
+agent-infra-internal platform-release-notes publish \
+  --tag "v{version}" \
+  --title "v{version}" \
+  --notes-file "{notes-file}" \
+  --expected-sha256 "{preview-sha256}"
+```
+
+命令在平台访问前复算摘要，不匹配时零写入；匹配时更新已有 Release，缺失时创建。`--dry-run` 只返回 planned operation。退出码为 `0` 时成功，`1` 表示稳定失败，`2` 表示网络或平台阻塞。

package/templates/.agents/rules/review-handshake.en.md

@@ -82,7 +82,7 @@ When an executor judges an item to be a key design decision that needs human rul
 - `severity` is always `decision`.
 - `status` starts as `needs-human-decision`, so the existing gate blocks it.
 - `evidence` points to the stable anchor `<artifact>#HD-N` (e.g. `plan-r2.md#HD-1`), not a drift-prone line number.
-- A human records the ruling with `ai decide <task-ref> <ordinal|ledger-id> <decision>`; the command flips the target row to `human-decided` and points `evidence` to an independent `HDR-N` ruling record.
+- A human records the ruling with `ai decide [--task <ref> | -t <ref>] (--item <ordinal|ledger-id> | -i <ordinal|ledger-id>) <decision>`; the command flips the target row to `human-decided` and points `evidence` to an independent `HDR-N` ruling record.
 
 > Viewing, deciding, and typed verification share the `lib/task/ledger.ts` domain semantics; no second parser is maintained.
 

package/templates/.agents/rules/review-handshake.zh-CN.md

@@ -82,7 +82,7 @@
 - `severity` 固定填 `decision`。
 - `status` 初始填 `needs-human-decision`，因此会被现有 gate 阻塞。
 - `evidence` 指向稳定锚点 `<artifact>#HD-N`（如 `plan-r2.md#HD-1`），不依赖易漂移的行号。
-- 人工使用 `ai decide <task-ref> <序号|账本ID> <裁决内容>` 记录裁定；命令把目标行翻为 `human-decided`，并让 `evidence` 指向独立 `HDR-N` 裁定记录。
+- 人工使用 `ai decide [--task <ref> | -t <ref>] (--item <序号|账本ID> | -i <序号|账本ID>) <裁决内容>` 记录裁定；命令把目标行翻为 `human-decided`，并让 `evidence` 指向独立 `HDR-N` 裁定记录。
 
 > 查看、裁决与 typed verification 共用 `lib/task/ledger.ts` 的领域语义，不维护第二 parser。
 

package/templates/.agents/rules/security-alerts.en.md

@@ -1,5 +1,20 @@
 # Security Alerts
 
-This code platform does not provide built-in security alert integration.
+Read this rule before importing or dismissing dependency or code-scanning alerts.
 
-Code scanning and dependency alert import or close actions are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and adapters. Track security work through local task artifacts or a platform-specific integration.
+## Shared entry point
+
+All callers use the shared security script and parse its single JSON result:
+
+```text
+bash .agents/scripts/security-alerts.sh read-dependabot --number {number}
+bash .agents/scripts/security-alerts.sh dismiss-dependabot --number {number} --reason {api-reason} --comment-file {file}
+bash .agents/scripts/security-alerts.sh read-codescan --number {number}
+bash .agents/scripts/security-alerts.sh dismiss-codescan --number {number} --reason {api-reason} --comment-file {file}
+```
+
+The result contains `status`, `operation`, and either `data` or `error.code` plus `error.message`. The status is one of `applied`, `no-op`, `degraded`, or `failed`. Diagnostics belong on stderr; stdout must contain exactly one JSON object.
+
+Read the current alert before any dismiss operation. A dismiss reason must use the provider API reason value, and the generated task or Issue comment must be passed through `--comment-file`.
+
+Do not invoke a provider CLI directly from a SKILL. A degraded or failed result must be reported accurately, and cancelled or failed operations must not be recorded as successful.

package/templates/.agents/rules/security-alerts.zh-CN.md

@@ -1,5 +1,20 @@
 # 安全告警
 
-当前代码平台未内置安全告警集成。
+在导入或关闭依赖告警、代码扫描告警前，先阅读本规则。
 
-自定义平台会跳过代码扫描和依赖告警的导入或关闭操作，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和适配器。请通过本地任务产物或平台专属集成跟踪安全工作。
+## 共享入口
+
+所有调用方都使用共享安全脚本，并解析其单个 JSON 结果：
+
+```text
+bash .agents/scripts/security-alerts.sh read-dependabot --number {number}
+bash .agents/scripts/security-alerts.sh dismiss-dependabot --number {number} --reason {api-reason} --comment-file {file}
+bash .agents/scripts/security-alerts.sh read-codescan --number {number}
+bash .agents/scripts/security-alerts.sh dismiss-codescan --number {number} --reason {api-reason} --comment-file {file}
+```
+
+结果包含 `status`、`operation`，以及 `data` 或 `error.code` 与 `error.message`。`status` 只能是 `applied`、`no-op`、`degraded` 或 `failed`。诊断信息写入 stderr；stdout 必须只包含一个 JSON 对象。
+
+任何关闭操作前都必须先读取当前告警。关闭原因必须使用 provider API 的 reason 值，生成的任务或 Issue 评论必须通过 `--comment-file` 传入。
+
+SKILL 不得直接调用 provider CLI。degraded 或 failed 结果必须如实报告，取消或失败的操作不得记录为成功。

package/templates/.agents/rules/sync-content-generation.en.md

@@ -0,0 +1,8 @@
+# Synchronized Content Generation Rules
+
+This rule applies to controlled generators that write `task.md` or lifecycle artifacts which are synchronized to an Issue. It constrains model output only; it does not parse, rewrite, or block hand-written or external content.
+
+- Render local, workspace, and temporary task-file references as inline code, such as `analysis.md` or `/workspace/file.md`; do not write them as Markdown links.
+- Render non-user-semantic `@` text, such as `@2x`, as inline code; preserve real user mentions, `@` inside email addresses, and fixed release-log formats according to their meaning.
+- Formal Issue, PR, commit, and external links may remain Markdown links.
+- When uncertain, keep ordinary text and do not guess a link target; do not introduce a runtime Markdown parser for this purpose.

package/templates/.agents/rules/sync-content-generation.zh-CN.md

@@ -0,0 +1,8 @@
+# 同步内容生成规则
+
+本规则适用于会写入 `task.md` 或生命周期产物并同步到 Issue 的受控生成端。它只约束模型生成，不解析、改写或阻断手写和外部正文。
+
+- 本地、工作区和临时任务文件引用使用行内代码文本，例如 `analysis.md`、`/workspace/file.md`；不要把它们写成 Markdown 链接。
+- 非用户语义的 `@` 文本（例如 `@2x`）使用行内代码文本；真实用户 mention、邮箱地址中的 `@` 和固定发布格式按语义保留。
+- 正式的 Issue、PR、commit 和外部链接可以保持 Markdown 链接。
+- 不确定时保留普通文本，不猜测链接目标；不要为此引入运行时 Markdown 解析器。