@fitlab-ai/agent-infra 0.8.4 → 0.9.0

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

@@ -11,7 +11,7 @@ This file defines four **independent** rules for a skill's "notify-user / Next s
 
 | Placeholder | Meaning | Rendered form |
 |-------------|---------|---------------|
-| `{task-ref}` | Current task **short id** | `#`-prefixed, e.g. `#15`; falls back to the full `TASK-id` when unavailable |
+| `{task-ref}` | Current task **short id** | Zero-padded bare digits, e.g. `15`; falls back to the full `TASK-id` when unavailable |
 | `{task-id}` | Current task **full id** | `TASK-YYYYMMDD-HHMMSS` |
 
 ## Scope
@@ -24,7 +24,7 @@ This file defines four **independent** rules for a skill's "notify-user / Next s
 
 The single source of truth for short ids is the registry `.agents/workspace/active/.short-ids.json` (via `task-short-id.js`). **Never** read the `short_id` field from task.md frontmatter (that field is not authoritative).
 
-Once the full `$task_id` is resolved, use the snippet below to look up the short id; it returns `#NN` on hit and falls back to the full `TASK-id` on miss:
+Once the full `$task_id` is resolved, use the snippet below to look up the short id; it returns bare `NN` on hit and falls back to the full `TASK-id` on miss:
 
 ```bash
 task_ref=$(node -e '
@@ -33,9 +33,9 @@ const out=cp.execSync("node .agents/scripts/task-short-id.js list",{encoding:"ut
 const ids=(JSON.parse(out).ids)||{};
 const full=process.argv[1];
 const hit=Object.entries(ids).find(([,v])=>v===full);
-process.stdout.write(hit?("#"+hit[0]):full);
+process.stdout.write(hit?hit[0]:full);
 ' "$task_id")
-# Example: $task_id=TASK-20260613-225809 -> task_ref=#15
+# Example: $task_id=TASK-20260613-225809 -> task_ref=15
 ```
 
 ## Fallback conditions
@@ -47,9 +47,9 @@ process.stdout.write(hit?("#"+hit[0]):full);
 
 `restore-task` re-allocates a short id when restoring a task (possibly different from before); the snippet picks up the new short id.
 
-## `#` prefix and shell quoting
+## Bare digits and shell safety
 
-Short ids are always rendered with a `#` prefix as `#NN`, matching how task.md frontmatter renders `short_id`. `#` starts a comment in bash, so pasting example commands depends on the TUI (both the bare numeric `NN` and `#NN` are accepted by `task-short-id.js resolve`).
+Short ids are always rendered as zero-padded bare digits `NN`. The removed `#NN` syntax must neither be generated nor accepted, avoiding bash comment interpretation.
 
 ## Agent output trailing line (Completed at)
 
@@ -83,7 +83,7 @@ This section is a **third standalone rule, co-equal with the two above**, used o
 `{h}` has the same meaning as the count line in each review skill's `reference/output-templates.md`: the number of rows in task.md `## 审查分歧账本` (Review Disagreement Ledger) for **this stage** (`stage ∈ {analysis|plan|code}`) whose `status = needs-human-decision` — **pending items only, excluding rows already `human-decided`**.
 
 - **`{h} = 0`**: do not emit this block; render "Next steps" exactly as the selected output-templates scenario.
-- **`{h} > 0`**: insert the block below **before** the selected scenario's "Next steps - <stage>" commands; the next-stage commands are still listed after the block.
+- **`{h} > 0`**: insert the block below **before** the selected scenario's "Next steps - <stage>" commands. This round may list only current-artifact revision and re-review commands, never cross-stage commands.
 
 ```text
 ⚠️ Pending human decisions ({h}) — please rule on each before continuing to the next stage:
@@ -93,13 +93,14 @@ This section is a **third standalone rule, co-equal with the two above**, used o
 
 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|HD-id>
+  - A single item's full background/options/impact/recommendation: ai task decisions {task-ref} <ordinal|ledger-id>
 
 To resolve:
-  1. In the task.md `## 人工裁决` section, record your ruling and rationale for each item above.
-  2. Flip the status of the matching row in `## 审查分歧账本` from `needs-human-decision` to `human-decided`.
+  - ai decide {task-ref} <ordinal|ledger-id> <decision and rationale>
 
-Note: until all those rows are flipped to `human-decided`, running the next-stage command directly will be blocked by gates such as complete-task (`needs-human-decision` is non-terminal). The next-stage commands are still listed below for use after the decisions are made.
+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.
+
+Note: until all those rows are flipped to `human-decided`, the stage gate blocks advancement (`needs-human-decision` is non-terminal). After the decisions, rerun the current review and let its new `stage-status` decide whether next-stage commands may be shown.
 ```
 
 Field values: `{ledger-id}` / `{stage}` / `{severity}` / `{evidence}` come from the same-named columns of the matching `## 审查分歧账本` row; `{summary}` comes from the artifact anchor referenced by `{evidence}` (e.g. the decision title at `plan.md#HD-1`), falling back to a one-line summary of the finding when no anchor title exists.

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

@@ -11,7 +11,7 @@
 
 | 占位符 | 含义 | 渲染形态 |
 |--------|------|----------|
-| `{task-ref}` | 当前任务**短号** | 带 `#` 前缀，如 `#15`；取不到时回退完整 `TASK-id` |
+| `{task-ref}` | 当前任务**短号** | 零填充裸数字，如 `15`；取不到时回退完整 `TASK-id` |
 | `{task-id}` | 当前任务**完整 ID** | `TASK-YYYYMMDD-HHMMSS` |
 
 ## 适用范围
@@ -24,7 +24,7 @@
 
 短号唯一真源是注册表 `.agents/workspace/active/.short-ids.json`（经 `task-short-id.js`）。**禁止**读取 task.md frontmatter 的 `short_id` 字段（该字段不可信）。
 
-在已解析出完整 `$task_id` 后，用以下片段反查短号；命中返回 `#NN`，未命中自动回退完整 `TASK-id`：
+在已解析出完整 `$task_id` 后，用以下片段反查短号；命中返回裸数字 `NN`，未命中自动回退完整 `TASK-id`：
 
 ```bash
 task_ref=$(node -e '
@@ -33,9 +33,9 @@ const out=cp.execSync("node .agents/scripts/task-short-id.js list",{encoding:"ut
 const ids=(JSON.parse(out).ids)||{};
 const full=process.argv[1];
 const hit=Object.entries(ids).find(([,v])=>v===full);
-process.stdout.write(hit?("#"+hit[0]):full);
+process.stdout.write(hit?hit[0]:full);
 ' "$task_id")
-# 示例：$task_id=TASK-20260613-225809 -> task_ref=#15
+# 示例：$task_id=TASK-20260613-225809 -> task_ref=15
 ```
 
 ## 回退条件
@@ -47,9 +47,9 @@ process.stdout.write(hit?("#"+hit[0]):full);
 
 `restore-task` 恢复任务时会重新分配短号（可能与历史不同），片段会取到新短号。
 
-## `#` 前缀与 shell 引用
+## 裸数字与 shell 安全
 
-短号统一渲染为带 `#` 前缀的 `#NN`，与 task.md frontmatter 的 `short_id` 渲染一致。`#` 在 bash 中是注释起始符，示例命令若直接粘贴需视 TUI 而定（裸数字 `NN` 与 `#NN` 都被 `task-short-id.js resolve` 接受）。
+短号统一渲染为零填充裸数字 `NN`。已移除的 `#NN` 语法不得生成或接受，避免 bash 将其解释为注释。
 
 ## Agent 输出收尾行（Completed at）
 
@@ -83,7 +83,7 @@ Completed at: YYYY-MM-DD HH:mm:ss
 `{h}` 含义与各 review 技能 `reference/output-templates.md` 计数行一致：task.md `## 审查分歧账本` 中**本阶段**（`stage ∈ {analysis|plan|code}`）`status = needs-human-decision` 的行数——**只含待裁决项，不含已 `human-decided`**。
 
 - **`{h} = 0`**：不输出本块，「下一步」按 output-templates 选定场景原样渲染。
-- **`{h} > 0`**：在选定场景的「下一步 - <阶段>」命令**之前**插入下面的块；下一阶段命令仍照常列在块之后。
+- **`{h} > 0`**：在选定场景的「下一步 - <阶段>」命令**之前**插入下面的块；本轮只能列当前产物的修订与复审路径，不得列跨阶段命令。
 
 ```text
 ⚠️ 待人工裁决（{h} 项）—— 请先逐项裁决，再继续下一阶段：
@@ -93,13 +93,14 @@ Completed at: YYYY-MM-DD HH:mm:ss
 
 查看详情：
   - 全部待裁决项：ai task decisions {task-ref}
-  - 单项完整背景/选项/影响/建议：ai task decisions {task-ref} <序号|HD-id>
+  - 单项完整背景/选项/影响/建议：ai task decisions {task-ref} <序号|账本ID>
 
 完成裁决：
-  1. 在 task.md `## 人工裁决` 段，逐项记录你对上述裁决项的裁定与理由。
-  2. 把 `## 审查分歧账本` 中对应行的 status 由 `needs-human-decision` 翻为 `human-decided`。
+  - ai decide {task-ref} <序号|账本ID> <裁决内容与理由>
 
-说明：在上述行全部翻为 `human-decided` 之前，直接执行下一阶段命令会被 complete-task 等 gate 拦截（`needs-human-decision` 为非终态）。下一阶段命令仍列在下方，供裁决完成后使用。
+该命令原子写入 `HDR-N` 裁定记录、把目标账本行翻为 `human-decided`、更新 evidence 与活动日志；不要手工只修改其中一部分。
+
+说明：在上述行全部翻为 `human-decided` 之前，阶段 gate 会拦截推进（`needs-human-decision` 为非终态）；裁决完成后重新执行当前 review，由新的 `stage-status` 结果决定是否展示下一阶段命令。
 ```
 
 字段取值：`{ledger-id}` / `{stage}` / `{severity}` / `{evidence}` 直接取自 `## 审查分歧账本` 对应行的同名列；`{摘要}` 取自 `{evidence}` 指向的产物锚点条目（如 `plan.md#HD-1` 的决策标题），无锚点标题时用该 finding 的一句话概述。

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

@@ -57,8 +57,8 @@ For every SKILL execution context not covered by any exemption above, the defaul
 
 When an open question is a key design decision that needs human judgment, the executor must:
 
-1. Write the decision's **detail block** (background / options / impact / recommendation) into the artifact's `## 人工裁决待办` (Pending Human Decisions) section, with a heading like `### HD-N：<title> [needs-human-decision]`; ordinary assumptions / open questions still go under `## Assumptions` / `## Open Questions` (`## 假设` / `## 未决问题`), and `## Open Questions` may keep a one-line pointer to the matching `### HD-N`.
-2. Upsert the matching `HD-` row in task.md `## Review Disagreement Ledger` according to `.agents/rules/review-handshake.md`, with `evidence` pointing to the stable anchor `<artifact>#HD-N`. The `HD-N` number is **globally unique** (scan existing `HD-(\d+)` in the ledger and take max+1, monotonically increasing across analysis / plan / code, never reused); see review-handshake.md for the allocation rule.
+1. Write a self-contained detail block per `.agents/rules/human-decision-context.md` into the artifact's `## 人工裁决待办` (Pending Human Decisions) section, with a heading like `### HD-N：<title> [needs-human-decision]`; ordinary assumptions / open questions still go under `## Assumptions` / `## Open Questions` (`## 假设` / `## 未决问题`), and `## Open Questions` may keep a one-line pointer to the matching `### HD-N`.
+2. Run `agent-infra-internal task-ledger {task-id} decision-next-id` to obtain the globally unique `HD-N`; after writing the detail block, run `decision-upsert --id {HD-N} --stage {stage} --artifact {artifact}`. The core writes the task.md ledger row and validates its evidence anchor; the model must not scan ids or assemble table rows.
 
 Use these checks together:
 
@@ -76,7 +76,7 @@ A mandatory human review checkpoint means:
 - Stop after producing the artifact: once the skill finishes an artifact such as `plan.md`, end the current invocation and wait for the user to explicitly trigger the next skill command
 - Do not pause mid-process to ask for input: do not insert interruptions such as "Do you prefer option A or B?" between execution steps
 
-If a key decision needs human judgment during execution, follow the "Key Design Decision Marking And Ledgering" rule above: write the detail block into the artifact's `## 人工裁决待办` (Pending Human Decisions) section as `### HD-N` and upsert the `HD-` ledger row, for the user to address at the review checkpoint; ordinary open questions still go to `## Open Questions` / `未决问题`.
+If a key decision needs human judgment during execution, follow the rule above and register the detail identity through the structured `decision-next-id` / `decision-upsert` commands for the user to address at the review checkpoint; ordinary open questions still go to `## Open Questions` / `未决问题`.
 
 ## Anchor Location
 

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

@@ -57,8 +57,8 @@
 
 当未决问题属于需要人工裁定的关键设计决策时，执行方必须：
 
-1. 把该决策的**详情块**（背景 / 选项 / 影响 / 推荐）写入产物的 `## 人工裁决待办` 段，标题形如 `### HD-N：<标题> [needs-human-decision]`；普通假设 / 未决问题仍分别写 `## 假设` / `## 未决问题`（`## Assumptions` / `## Open Questions`），`## 未决问题` 可保留一行指针指向对应 `### HD-N`。
-2. 按 `.agents/rules/review-handshake.md` 在 task.md `## 审查分歧账本` upsert 对应 `HD-` 行，evidence 指向稳定锚点 `<artifact>#HD-N`。`HD-N` 编号**全局唯一**（扫描账本已有 `HD-(\d+)` 取 max+1，跨 analysis / plan / code 单调递增、禁止复用），分配规则详见 review-handshake.md。
+1. 按 `.agents/rules/human-decision-context.md` 写出自足的详情块，放入产物的 `## 人工裁决待办` 段，标题形如 `### HD-N：<标题> [needs-human-decision]`；普通假设 / 未决问题仍分别写 `## 假设` / `## 未决问题`（`## Assumptions` / `## Open Questions`），`## 未决问题` 可保留一行指针指向对应 `### HD-N`。
+2. 先调用 `agent-infra-internal task-ledger {task-id} decision-next-id` 取得全局唯一 `HD-N`，写出详情块后调用 `decision-upsert --id {HD-N} --stage {stage} --artifact {artifact}`；由核心写入 task.md 账本并校验证据锚点，模型不得扫描编号或拼表格行。
 
 判定时同时使用以下检查：
 
@@ -76,7 +76,7 @@
 - **产出后停止**：技能完成产物（如 `plan.md`）后立即结束本轮调用，等待用户主动触发下一个技能命令
 - **不是过程中暂停征求意见**：不允许在执行步骤之间插入「请问您倾向 A 还是 B？」之类的中断
 
-如果在执行过程中发现需要用户裁定的关键决策，按上文「关键设计决策标记与落账」处理：详情块写入产物 `## 人工裁决待办` 的 `### HD-N`、回写 `HD-` 账本行，由用户在审查检查点统一回应；普通未决问题仍写 `## 未决问题` / `Open Questions`。
+如果在执行过程中发现需要用户裁定的关键决策，按上文「关键设计决策标记与落账」处理：通过 `decision-next-id` / `decision-upsert` 结构化命令登记详情块与账本身份，由用户在审查检查点统一回应；普通未决问题仍写 `## 未决问题` / `Open Questions`。
 
 ## 锚点位置
 

package/templates/.agents/rules/pr-checks-commands.en.md

@@ -1,5 +1,18 @@
-# PR Checks Platform Commands
+# Required-checks Platform Intents
 
-This code platform does not provide built-in pull request check commands.
+Typed intents own required-only selection, polling deadlines, run/job resolution, and log retrieval. The skill/model owns failure classification, root-cause analysis, minimum fixes, tests, and authorized commit/push actions.
 
-Platform-specific check monitoring is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates. Keep local task artifacts as the source of truth, or install a platform-specific template pack before running the `watch-pr` skill.
+```bash
+agent-infra-internal platform-checks inspect {task-id}
+
+agent-infra-internal platform-checks watch {task-id} \
+  --interval-seconds 30 --deadline-seconds 1800
+
+agent-infra-internal platform-checks resolve-run {task-id} \
+  --check-name {check-name} [--details-url {details-url}]
+
+agent-infra-internal platform-checks logs {task-id} \
+  --run {run-id} [--job {job-id}]
+```
+
+`checks.state` is `passed|failed|pending|timed-out|cancelled|no-required`. Green/no-required exits 0; definite failure/cancellation exits 1; pending, timeout, or network blocking exits 2. Each platform adapter validates its own dependencies before operations and preserves dependency or deterministic platform errors without compatibility degradation. Run resolution prefers a validated details URL and otherwise requires one exact PR-head/check-name match. Platform intents never edit business code or push.

package/templates/.agents/rules/pr-checks-commands.github.en.md

@@ -1,62 +1,18 @@
-# PR Checks Platform Commands (GitHub)
+# Required-checks Platform Intents
 
-Read this file before watching a PR's required checks, resolving a failing run, pulling failure logs, or reading the current branch's PR. The `watch-pr` skill's platform-specific commands live here; the skill body and `reference/` stay platform-agnostic.
-
-## Current Branch PR / Repository Info
+The GitHub adapter requires `gh >= 2.16.0`. Platform context checks this dependency before any GitHub API, PR, or checks operation. Projects that do not select GitHub neither probe nor depend on `gh`.
 
 ```bash
-gh pr view --json number -q .number                  # PR number for the current branch
-gh pr view {pr#} --json headRefOid -q .headRefOid    # PR head SHA
-gh repo view --json nameWithOwner -q .nameWithOwner  # {owner}/{repo}
-```
+agent-infra-internal platform-checks inspect {task-id}
 
-If `gh` is not authenticated or a command fails, stop or degrade per the calling skill's error handling.
+agent-infra-internal platform-checks watch {task-id} \
+  --interval-seconds 30 --deadline-seconds 1800
 
-## Watch Required Checks
+agent-infra-internal platform-checks resolve-run {task-id} \
+  --check-name {check-name} [--details-url {details-url}]
 
-```bash
-gh pr checks {pr#} --required --watch --fail-fast -i 30 \
-  --json name,bucket,link,workflow
+agent-infra-internal platform-checks logs {task-id} \
+  --run {run-id} [--job {job-id}]
 ```
 
-- `--required`: include only checks the repository's branch protection marks as required.
-- `--watch`: block until those checks finish; `--fail-fast`: exit watch on the first failure.
-- `-i 30`: poll every 30 seconds (backoff). **Overall time cap default 30 minutes (1800 seconds)**: use the timeout mechanism that matches the execution environment; on timeout, treat as "pending" (exit code 8).
-  - POSIX shell: `timeout 1800 gh pr checks {pr#} --required --watch --fail-fast -i 30 …`
-  - PowerShell (Windows): use a job timeout —
-    ```powershell
-    $job = Start-Job { gh pr checks {pr#} --required --watch --fail-fast -i 30 }
-    if (Wait-Job $job -Timeout 1800) { Receive-Job $job } else { Stop-Job $job; <treat as "pending"> }
-    ```
-  - Platform-neutral fallback (no external timeout tool): record the start time, loop `gh pr checks {pr#} --required --json name,bucket,link,workflow` **without** `--watch`, sleeping `-i` seconds each round and checking whether any `bucket` is still `pending`; if the elapsed time reaches 1800 seconds without finishing, exit the loop and treat as "pending".
-- The `bucket` field of `--json` classifies each check as `pass` / `fail` / `pending` / `skipping` / `cancel`.
-
-Exit code semantics:
-
-| Exit code | Meaning | Outcome class |
-|-----------|---------|---------------|
-| 0 | all required checks passed | all green |
-| 1 | at least one failed / errored | failure |
-| 8 | still pending (watch timed out or was cut off by `timeout`) | pending |
-
-Old `gh` (< 2.93) without `--required`: fall back to `gh pr checks {pr#} --watch --fail-fast` (i.e. "all checks must succeed"), and note this degradation in the help/report and suggest upgrading `gh`.
-
-## Resolve a Failing Run id and Pull Logs
-
-`gh pr checks --json` does not return a run id directly, but it returns each failing check's `link` (a URL to the run/job). Resolve in this deterministic order:
-
-1. Extract from the failing check's `link` via regex: `https://github.com/{owner}/{repo}/actions/runs/(\d+)(?:/job/(\d+))?` → group 1 is the run id (optional group 2 is the job id).
-2. When `link` is not a run URL or cannot be parsed, query check-runs by head SHA:
-   ```bash
-   sha=$(gh pr view {pr#} --json headRefOid -q .headRefOid)
-   gh api "repos/{owner}/{repo}/commits/$sha/check-runs" \
-     --jq '.check_runs[] | select(.name=="{failed-check-name}") | .details_url'
-   ```
-   then extract the run id from `details_url` the same way.
-3. If neither path yields a run id → treat as "unlocatable" and use the skill's help exit; do not self-heal blindly.
-
-Once the run id is known, pull the failure logs:
-
-```bash
-gh run view {run-id} --log-failed
-```
+The core owns required-only selection, deadlines, exact run/job resolution, and faithful logs. Green/no-required exits 0; definite failure exits 1; pending, timeout, or network blocking exits 2. Missing dependencies, unsupported versions, and deterministic platform failures preserve their structured errors without compatibility degradation. The skill/model still owns diagnosis, fixes, tests, and authorized commit/push actions.

package/templates/.agents/rules/pr-checks-commands.github.zh-CN.md

@@ -1,62 +1,34 @@
-# PR 检查平台命令（GitHub）
+# PR required checks 平台意图
 
-在监控 PR 的 required checks、解析失败 run、拉取失败日志或读取当前分支 PR 前先读取本文件。`watch-pr` 技能的平台专属命令集中在此，技能正文与 `reference/` 保持平台无关。
+required checks 的筛选、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。SKILL/模型只负责失败分类、根因分析、最小修复和授权后的提交推送。
 
-## 当前分支 PR / 仓库信息
+GitHub adapter 要求 `gh >= 2.16.0`。平台上下文会在任何 GitHub API、PR 或 checks 操作前检查该依赖；未选择 GitHub 平台时不探测也不依赖 `gh`。
+
+## 快照与监控
 
 ```bash
-gh pr view --json number -q .number          # 当前分支对应的 PR 号
-gh pr view {pr#} --json headRefOid -q .headRefOid   # PR head SHA
-gh repo view --json nameWithOwner -q .nameWithOwner # {owner}/{repo}
+agent-infra-internal platform-checks inspect {task-id}
+
+agent-infra-internal platform-checks watch {task-id} \
+  --interval-seconds 30 --deadline-seconds 1800
 ```
 
-`gh` 未认证或命令失败时，按调用方技能的错误处理停止或降级。
+结构化 `checks.state` 为 `passed|failed|pending|timed-out|cancelled|no-required`。`passed|no-required` 退出 0；确定失败/取消退出 1；pending、timeout 或网络阻塞退出 2。依赖缺失、版本过低和确定性平台错误直接返回其原始结构化错误，不执行兼容降级。
 
-## 监控 required checks
+## 定位失败 run/job
 
 ```bash
-gh pr checks {pr#} --required --watch --fail-fast -i 30 \
-  --json name,bucket,link,workflow
+agent-infra-internal platform-checks resolve-run {task-id} \
+  --check-name {check-name} [--details-url {details-url}]
 ```
 
-- `--required`：只纳入仓库分支保护标记为 required 的 checks。
-- `--watch`：阻塞直到这些 checks 全部跑完；`--fail-fast`：出现首个失败即退出 watch。
-- `-i 30`：轮询间隔 30 秒（退避）。**总时长上限默认 30 分钟（1800 秒）**：按执行环境选用对应的超时方式，超时即按「挂起」处理（退出码 8）。
-  - POSIX shell：`timeout 1800 gh pr checks {pr#} --required --watch --fail-fast -i 30 …`
-  - PowerShell（Windows）：用作业超时——
-    ```powershell
-    $job = Start-Job { gh pr checks {pr#} --required --watch --fail-fast -i 30 }
-    if (Wait-Job $job -Timeout 1800) { Receive-Job $job } else { Stop-Job $job; <按「挂起」处理> }
-    ```
-  - 平台中立回退（无外部超时工具时）：记录开始时间，循环执行**不带** `--watch` 的 `gh pr checks {pr#} --required --json name,bucket,link,workflow`，每轮 sleep `-i` 秒并检查 `bucket` 是否仍有 `pending`；累计时长 ≥ 1800 秒仍未结束 → 退出循环按「挂起」处理。
-- `--json` 的 `bucket` 字段把每个 check 归类为 `pass` / `fail` / `pending` / `skipping` / `cancel`。
-
-退出码语义：
-
-| 退出码 | 含义 | 结果分类 |
-|--------|------|----------|
-| 0 | 全部 required checks 通过 | 全绿 |
-| 1 | 至少一个失败 / 出错 | 失败 |
-| 8 | 仍有 pending（watch 超时或被 `timeout` 截断） | 挂起 |
-
-旧版 `gh`（< 2.93）若不支持 `--required`：回退为 `gh pr checks {pr#} --watch --fail-fast`（即「所有 check 必须 success」），并在求助/报告中注明该降级、建议升级 `gh`。
+core 优先验证详情链接；否则按 PR head SHA 与 exact check name 查询。零个或多个候选均 fail closed，不选择其他 run。
 
-## 解析失败 run id 并拉日志
-
-`gh pr checks --json` 不直接返回 run id，但返回失败 check 的 `link`（指向 run/job 的 URL）。按确定性顺序解析：
-
-1. 从失败 check 的 `link` 用正则提取：`https://github.com/{owner}/{repo}/actions/runs/(\d+)(?:/job/(\d+))?` → 第 1 组为 run id（可选第 2 组为 job id）。
-2. `link` 非 run URL 或无法解析时，用 head SHA 查 check-runs：
-   ```bash
-   sha=$(gh pr view {pr#} --json headRefOid -q .headRefOid)
-   gh api "repos/{owner}/{repo}/commits/$sha/check-runs" \
-     --jq '.check_runs[] | select(.name=="{failed-check-name}") | .details_url'
-   ```
-   再从 `details_url` 同法提取 run id。
-3. 两路都拿不到 run id → 视为「不可定位」，按技能的求助出口处理，不盲目自愈。
-
-拿到 run id 后拉失败日志：
+## 获取失败日志
 
 ```bash
-gh run view {run-id} --log-failed
+agent-infra-internal platform-checks logs {task-id} \
+  --run {run-id} [--job {job-id}]
 ```
+
+日志结果保真返回；缺失、权限、网络和资源不存在使用稳定错误码区分。平台 intent 不修改业务代码、不测试、不提交也不推送。

package/templates/.agents/rules/pr-checks-commands.zh-CN.md

@@ -1,5 +1,32 @@
-# PR 检查平台命令
+# PR required checks 平台意图
 
-当前代码平台未内置 Pull Request 检查命令支持。
+required checks 的筛选、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。SKILL/模型只负责失败分类、根因分析、最小修复和授权后的提交推送。
 
-自定义平台会跳过平台专属的检查监控，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。请以本地任务产物作为事实来源，或先安装平台专属模板包再运行 `watch-pr` 技能。
+## 快照与监控
+
+```bash
+agent-infra-internal platform-checks inspect {task-id}
+
+agent-infra-internal platform-checks watch {task-id} \
+  --interval-seconds 30 --deadline-seconds 1800
+```
+
+结构化 `checks.state` 为 `passed|failed|pending|timed-out|cancelled|no-required`。`passed|no-required` 退出 0；确定失败/取消退出 1；pending、timeout 或网络阻塞退出 2。平台 adapter 必须在操作前验证自身依赖；依赖或确定性平台错误直接透传，不执行兼容降级。
+
+## 定位失败 run/job
+
+```bash
+agent-infra-internal platform-checks resolve-run {task-id} \
+  --check-name {check-name} [--details-url {details-url}]
+```
+
+core 优先验证详情链接；否则按 PR head SHA 与 exact check name 查询。零个或多个候选均 fail closed，不选择其他 run。
+
+## 获取失败日志
+
+```bash
+agent-infra-internal platform-checks logs {task-id} \
+  --run {run-id} [--job {job-id}]
+```
+
+日志结果保真返回；缺失、权限、网络和资源不存在使用稳定错误码区分。平台 intent 不修改业务代码、不测试、不提交也不推送。

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

@@ -1,5 +1,32 @@
-# PR Sync
+# PR Summary Synchronization
 
-This code platform does not provide built-in pull request synchronization.
+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.
 
-PR creation, metadata updates, labels, milestones, assignees, and summary comments are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and adapters. Keep local task artifacts up to date.
+## Inputs
+
+```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*`. The summary covers scope, tests, review history, and exactly one manual-validation state.
+
+## Publish
+
+Write only the summary body to a file, without marker or SHA:
+
+```bash
+agent-infra-internal platform-pr summary-sync {task-id} \
+  --agent {agent} --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.
+
+`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.
+
+For a linked task, the caller records a structured warning:
+
+```bash
+agent-infra-internal task-warning {task-id} add --step {step} --severity WARNING \
+  --code COMMENT_SYNC_FAILED --target pr-summary --message "{reason}" \
+  --action "Restore comment permission or connectivity and rerun this step"
+```

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

@@ -1,135 +1,32 @@
-# PR Summary Sync
+# PR Summary Synchronization
 
-Read this file before syncing the single reviewer-facing PR summary comment.
+The model writes the semantic reviewer summary. Typed core owns canonical artifact selection, marker/HEAD wrapping, paginated comment lookup, and reconciliation.
 
-## Scope
-
-Current callers:
-- `create-pr`: create or update the summary comment when the PR is opened
-- `commit`: refresh the summary comment on an existing PR when needed
-- `complete-manual-validation`: update the summary comment in place after manual validation passes, and write a validation artifact that later aggregation can reuse
-
-If another skill needs to refresh the PR summary later, point that skill's reference file at this rule first, then document only the skill-specific trigger and failure behavior there.
-
-## Hidden Marker
-
-Use this hidden marker:
+```bash
+agent-infra-internal platform-pr summary-context {task-id}
 
-```html
-<!-- sync-pr:{task-id}:summary -->
+agent-infra-internal platform-pr summary-sync {task-id} \
+  --agent {agent} --body-file {summary-body-file}
 ```
 
-Within one PR, a given `{task-id}` must have only one summary comment with this marker.
-
-## Aggregation Inputs
-
-Aggregate the latest artifacts in the task directory:
-- `plan.md` or the latest `plan-r{N}.md`
-- `code.md` or the latest `code-r{N}.md`
-- `review-code.md` or the latest `review-code-r{N}.md`
-- `manual-validation.md` or the latest `manual-validation-r{N}.md`
-
-Aggregation rules:
-- extract 2-4 self-contained technical decisions from `plan*`
-- build the review-history table from `review-code*` and `code*`
-- extract the test summary from `code*`
-- if the latest `manual-validation*` artifact has a passed verdict, render the manual-validation section first as `### ✅ Manual Validation Passed`, with a concise validation time, scope, and notes summary
-- if one artifact class is missing, treat it as "no data for this stage" and continue
-- Manual verification section: include only post-code-stage checks that still require a human to execute or judge and that the AI cannot close on its own.
-  - **Admission boundary**: the verification result depends on a real environment, permissions, account, external system, or human judgment, and cannot be closed by an agent rerunning tests, adding checks, or continuing the fix loop.
-  - **Sources**: `review-code*` "Manual Validation Items", plus `code*` items that satisfy the boundary above.
-  - **Wording**: each retained item must state at least "what to verify + location (file/change/scope) + why only a human can verify it".
-  - **Rendering priority**:
-    1. the latest `manual-validation*` artifact has a passed verdict -> heading `### ✅ Manual Validation Passed` + validation summary.
-    2. no passed artifact and retained items exist -> heading `### ⚠️ Manual Verification Required` + item list.
-    3. no passed artifact and no retained items -> heading `### ✅ No Manual Verification Needed` and a single line `No items in this change require manual confirmation.`, with no item list.
+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.
 
-## Comment Body Template
-
-Use this canonical comment body template:
+The canonical comment envelope produced by the core is:
 
 ```markdown
 <!-- sync-pr:{task-id}:summary -->
 <!-- last-commit: {git-head-sha} -->
 ## Review Summary
-
-> **{agent}** · {task-id}
-
-**Updated At**: {current-time}
-
 {manual-validation-section}
-
 ### Key Technical Decisions
-
-- {decision-1}
-- {decision-2}
-
 ### Review History
-
-| Round | Verdict | Finding Counts | Fix Status |
-|-------|---------|----------------|------------|
-| Round 1 | Pending | N/A | N/A |
-
 ### Test Results
-
-- {test-summary}
-
----
-*Generated by {agent} · Internal tracking: {task-id}*
 ```
 
-> Render `{manual-validation-section}` per the "manual verification section" aggregation rule above: passed artifact → `### ✅ Manual Validation Passed` heading + validation summary; retained items → `### ⚠️ Manual Verification Required` heading + quote + item list; none → `### ✅ No Manual Verification Needed` heading + a single line `No items in this change require manual confirmation.` (no ⚠️, no list).
-
-## Comment Lookup And Update
-
-Fetch existing comments through the Issues comments API, not the dedicated PR comments API.
-
-Before this section runs, the caller must resolve `upstream_repo` by following `.agents/rules/issue-pr-commands.md` / `.agents/rules/issue-sync.md`.
-
-Process:
-1. Fetch existing PR comments and locate the comment ID that starts with `<!-- sync-pr:{task-id}:summary -->`
-2. When rendering the body, always write the current `git rev-parse HEAD` result into `<!-- last-commit: {git-head-sha} -->`
-3. If it does not exist, create it once as a fallback
-4. If it exists and the body is identical, skip the write
-5. If it exists and the body changed, PATCH it in place
-
-When updating an existing comment, use:
+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.
 
 ```bash
-gh api "repos/$upstream_repo/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
-{comment-body}
-EOF
-)"
+agent-infra-internal task-warning {task-id} add --step {step} --severity WARNING \
+  --code COMMENT_SYNC_FAILED --target pr-summary --message "{reason}" \
+  --action "Restore comment permission or connectivity and rerun this step"
 ```
-
-## Shell Safety Rules
-
-1. Read local artifact content first, then inline the actual text into a `<<'EOF'` heredoc.
-2. Do not use command substitution or variable expansion inside the heredoc.
-3. Do not use `echo` to construct bodies that contain `<!-- -->`; use `cat <<'EOF'` or `printf '%s\n'`.
-
-## Error Handling
-
-| Failure Point | Handling |
-|--------|------|
-| `task.md` cannot be read | skip sync and let the later verification gate report it |
-| aggregation input is missing | warn and continue with the available data |
-| `gh api` GET/PATCH/POST fails | warn and continue; whether the current skill should block is decided by the caller |
-| `pr_number` points to a missing PR | warn with `PR #{pr-number} not found` and continue |
-
-When the caller has a `{task-id}` / task directory and GET/PATCH/POST fails, record a Workflow Warning:
-
-```bash
-node .agents/scripts/workflow-warnings.js add .agents/workspace/active/{task-id} \
-  --step pr-sync --severity ACTION_REQUIRED --code COMMENT_SYNC_FAILED \
-  --target "pr-summary" --message "{reason}" \
-  --action "Fix GitHub API / network issues and rerun the workflow step that triggers PR summary sync"
-```
-
-## Result Reporting
-
-Return one of these normalized results so callers can reuse it in Activity Log entries or user output:
-- `summary created`
-- `summary updated`
-- `summary skipped (no diff)`
-- `summary failed: <reason>`