@fitlab-ai/agent-infra 0.8.5 → 0.9.1

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

@@ -1,135 +1,57 @@
 # PR 摘要同步
 
-在同步 reviewer 面向的唯一 PR 摘要评论之前先读取本文件。
+PR 摘要的语义聚合由模型完成；canonical 产物选择、marker、当前 HEAD、分页评论查找和 create/update/no-op 由 typed core 负责。
 
-## 适用范围
-
-当前调用方：
-- `create-pr`：首次创建或更新 PR 摘要评论
-- `commit`：在已有 PR 上按需刷新摘要评论
-- `complete-manual-validation`：人工验证完成后原地更新摘要评论，并写入可被后续聚合复用的验证产物
-
-如果后续 skill 也需要刷新 PR 摘要，先在对应 skill 的 reference 中引用本 rule，再补充该 skill 自身的触发条件和失败语义。
-
-## 隐藏标记
-
-统一使用以下隐藏标记：
+## 聚合输入
 
-```html
-<!-- sync-pr:{task-id}:summary -->
+```bash
+agent-infra-internal platform-pr summary-context {task-id}
 ```
 
-同一个 PR 中，同一个 `{task-id}` 只能维护一条带该标记的摘要评论。
+只使用返回的 canonical latest `plan*`、`review-plan*`、`code*`、`review-code*`、`manual-validation*`（包括 `manual-validation.md`）。模型据此生成 reviewer 摘要正文，至少包含：
 
-## 聚合输入
+- 变更摘要与实现范围
+- 测试结果
+- 审查历程与当前结论
+- 人工校验三态：`### ⚠️ 需人工校验`、`### ✅ 人工验证已通过` 或 `### ✅ 无需人工校验`
+
+保留人工校验项时，每条写明校验内容、定位和只能人工完成的原因。
 
-聚合当前任务目录中的最新产物：
-- `plan.md` 或最新 `plan-r{N}.md`
-- `code.md` 或最新 `code-r{N}.md`
-- `review-code.md` 或最新 `review-code-r{N}.md`
-- `manual-validation.md` 或最新 `manual-validation-r{N}.md`
-
-聚合规则：
-- 从 `plan*` 提取 2-4 条自包含的关键技术决策
-- 用 `review-code*` 与 `code*` 构建审查历程表
-- 从 `code*` 提取测试结果摘要
-- 如果最新 `manual-validation*` 产物结论为通过，需人工校验段落优先渲染为 `### ✅ 人工验证已通过`，并摘要验证时间、验证范围和验证说明
-- 某一类产物缺失时，按“无该阶段数据”处理并继续生成
-- 需人工校验段落：只收进入 code 阶段后仍需人实际执行或判断、AI 无法自行关闭的校验点。
-  - **准入边界**：校验结论依赖真实环境、权限、账号、外部系统或人工判断，且无法通过 agent 重跑测试、补充检查或继续修复自行关闭。
-  - **来源**：`review-code*` 的「人工校验项」，以及 `code*` 中满足上述边界的校验点。
-  - **写法**：每条保留项至少写明「校验什么 + 定位（文件/改动/范围）+ 为什么只能由人校验」。
-  - **渲染优先级**：
-    1. 最新 `manual-validation*` 产物结论为通过 -> 标题 `### ✅ 人工验证已通过` + 验证摘要。
-    2. 没有通过产物且有保留项 -> 标题 `### ⚠️ 需人工校验` + 条目列表。
-    3. 没有通过产物且无保留项 -> 标题 `### ✅ 无需人工校验`，正文一行 `本次改动无需人工确认事项。`，不带条目列表。
-
-## 评论体模板
-
-评论正文使用以下唯一权威模板：
+core 最终包装出的 canonical 评论结构为：
 
 ```markdown
 <!-- sync-pr:{task-id}:summary -->
 <!-- last-commit: {git-head-sha} -->
 ## 审查摘要
-
-> **{agent}** · {task-id}
-
-**更新时间**：{当前时间}
-
 {manual-validation-section}
-
 ### 关键技术决策
-
-- {decision-1}
-- {decision-2}
-
 ### 审查历程
-
-| 轮次 | 结论 | 问题统计 | 修复状态 |
-|------|------|----------|----------|
-| Round 1 | Pending | N/A | N/A |
-
 ### 测试结果
-
-- {test-summary}
-
----
-*由 {agent} 自动生成 · 内部追踪：{task-id}*
 ```
 
-> `{manual-validation-section}` 按上文「需人工校验段落」聚合规则渲染：已通过产物 → `### ✅ 人工验证已通过` 标题 + 验证摘要；有保留项 → `### ⚠️ 需人工校验` 标题 + 引用说明 + 条目列表；无保留项 → `### ✅ 无需人工校验` 标题 + 一行 `本次改动无需人工确认事项。`（不带 ⚠️、不带列表）。
-
-## 评论查找与更新
-
-已有评论必须通过 Issues comments API 获取，而不是单独的 PR comments API。
+## 发布
 
-调用方在执行本章节前，必须先按 `.agents/rules/issue-pr-commands.md` / `.agents/rules/issue-sync.md` 完成 `upstream_repo` 检测。
-
-处理顺序：
-1. 获取 PR 上现有 comments，查找以 `<!-- sync-pr:{task-id}:summary -->` 开头的评论 ID
-2. 渲染评论正文时，始终写入当前 `git rev-parse HEAD` 的结果到 `<!-- last-commit: {git-head-sha} -->`
-3. 不存在时，POST 创建一条新评论作为兜底
-4. 已存在且正文完全相同时，跳过写入
-5. 已存在且正文有变化时，PATCH 原地更新
-
-更新已有评论时，使用如下模式：
+把聚合后的纯正文写入 `{summary-body-file}`，不要自行添加 marker 或 commit SHA：
 
 ```bash
-gh api "repos/$upstream_repo/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
-{comment-body}
-EOF
-)"
+agent-infra-internal platform-pr summary-sync {task-id} \
+  --agent {agent} --body-file {summary-body-file}
 ```
 
-## Shell 安全规则
+core 会包装唯一 `<!-- sync-pr:{task-id}:summary -->` 和当前 `<!-- last-commit: ... -->`，分页查找 PR 普通评论：不存在则创建、正文变化则原地更新、无差异则 no-op、重复 marker 则稳定失败。正文通过文件输入，调用方不得拼 shell/heredoc。
 
-1. 先读取本地产物内容，再将实际文本内联到 `<<'EOF'` heredoc 中。
-2. 禁止在 heredoc 中使用命令替换或变量展开。
-3. 构造含 `<!-- -->` 的正文时禁止使用 `echo`，统一使用 `cat <<'EOF'` 或 `printf '%s\n'`。
+## 结果回传
 
-## 错误处理
+- `applied`：`summary created` 或 `summary updated`
+- `no-op`：`summary skipped (no diff)`
+- `failed|blocked`：`summary failed: {error.code}: {error.message}`
 
-| 失败点 | 处理 |
-|--------|------|
-| `task.md` 无法读取 | 跳过同步，交由后续 verification gate 报错 |
-| 聚合输入缺失 | 记警告并按现有数据继续生成 |
-| `gh api` GET/PATCH/POST 失败 | 输出警告并继续；是否阻塞当前 skill 由调用方决定 |
-| `pr_number` 指向的 PR 不存在 | 输出 `PR #{pr-number} not found` 警告并继续 |
+`create-pr` 中摘要失败不回滚已创建 PR；`commit` 中只记 warning，不回滚 commit；`complete-manual-validation` 在 canonical artifact 落盘后调用同一 intent 原地刷新。
 
-当调用方存在 `{task-id}` / task 目录且 GET/PATCH/POST 失败时，记录 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 "修复 GitHub API / 网络问题后重跑触发 PR 摘要同步的 workflow 步骤"
+agent-infra-internal task-warning {task-id} add --step {step} --severity WARNING \
+  --code COMMENT_SYNC_FAILED --target pr-summary --message "{reason}" \
+  --action "修复评论权限或平台连接后重跑当前步骤"
 ```
-
-## 结果回传
-
-统一回传以下结果之一，供调用方在 Activity Log 或用户输出中复用：
-- `summary created`
-- `summary updated`
-- `summary skipped (no diff)`
-- `summary failed: <reason>`

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

@@ -1,5 +1,45 @@
-# PR 同步
+# PR 摘要同步
 
-当前代码平台未内置 Pull Request 同步支持。
+PR 摘要的语义聚合由模型完成；canonical 产物选择、marker、当前 HEAD、分页评论查找和 create/update/no-op 由 typed core 负责。
 
-自定义平台会跳过 PR 创建、元数据更新、标签、里程碑、负责人和摘要评论同步，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和适配器。请保持本地任务产物更新。
+## 聚合输入
+
+```bash
+agent-infra-internal platform-pr summary-context {task-id}
+```
+
+只使用返回的 canonical latest `plan*`、`review-plan*`、`code*`、`review-code*`、`manual-validation*`。模型据此生成 reviewer 摘要正文，至少包含：
+
+- 变更摘要与实现范围
+- 测试结果
+- 审查历程与当前结论
+- 人工校验三态：`### ⚠️ 需人工校验`、`### ✅ 人工验证已通过` 或 `### ✅ 无需人工校验`
+
+保留人工校验项时，每条写明校验内容、定位和只能人工完成的原因。
+
+## 发布
+
+把聚合后的纯正文写入 `{summary-body-file}`，不要自行添加 marker 或 commit SHA：
+
+```bash
+agent-infra-internal platform-pr summary-sync {task-id} \
+  --agent {agent} --body-file {summary-body-file}
+```
+
+core 会包装唯一 `<!-- sync-pr:{task-id}:summary -->` 和当前 `<!-- last-commit: ... -->`，分页查找 PR 普通评论：不存在则创建、正文变化则原地更新、无差异则 no-op、重复 marker 则稳定失败。正文通过文件输入，调用方不得拼 shell/heredoc。
+
+## 结果回传
+
+- `applied`：`summary created` 或 `summary updated`
+- `no-op`：`summary skipped (no diff)`
+- `failed|blocked`：`summary failed: {error.code}: {error.message}`
+
+`create-pr` 中摘要失败不回滚已创建 PR；`commit` 中只记 warning，不回滚 commit；`complete-manual-validation` 在 canonical artifact 落盘后调用同一 intent 原地刷新。
+
+关联任务的摘要失败由调用方登记结构化告警：
+
+```bash
+agent-infra-internal task-warning {task-id} add --step {step} --severity WARNING \
+  --code COMMENT_SYNC_FAILED --target pr-summary --message "{reason}" \
+  --action "修复评论权限或平台连接后重跑当前步骤"
+```

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

@@ -1,5 +1,5 @@
 # Release Commands
 
-This code platform does not provide built-in release commands.
+This code platform does not provide a release-note adapter.
 
-Remote release automation is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and scripts. Continue using local release artifacts or your platform-specific release process.
+Use `agent-infra-internal platform-release-notes context` to receive a structured `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op. Do not probe another platform client. Publishing remains a no-op until an adapter is provided.

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

@@ -1,52 +1,22 @@
 # Release Platform Commands
 
-Read this file before loading release history, querying merged PRs, or publishing the Release notes.
+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.
 
-## Query Releases
+## Collect Release-note Context
 
 ```bash
-gh release list --limit {limit} --json tagName,isDraft,isPrerelease
-gh release view "{tag}" --json body,url
+agent-infra-internal platform-release-notes context \
+  --from-tag "v{prev-version}" --to-tag "v{version}" \
+  --branch "{branch}" --history-limit 3
 ```
 
-## Query Merged PRs
+The result contains release history, pull requests, closing Issues, and normalized contributor identities. Unsupported platforms return a stable `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op.
 
-```bash
-gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels
-```
-
-When needed, read the linked Issue:
-
-```bash
-gh issue view {issue-number} --json number,title,labels,url
-```
-
-## Contributor Mapping Helpers
-
-Merged PR queries used for release notes should include authors when contributors are needed:
-
-```bash
-gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels,author
-```
-
-Linked Issue queries used for reporter attribution should include the author:
-
-```bash
-gh issue view {issue-number} --json number,title,labels,url,author
-```
-
-Map GitHub no-reply emails with this rule: if `Name <email>` contains an email matching `(\d+\+)?(\S+?)@users\.noreply\.github\.com`, use the second capture group lowercased as the login. This covers both `{id}+{login}@users.noreply.github.com` and `{login}@users.noreply.github.com`.
-
-## Publish the Release Notes
-
-The GitHub Release for `v{version}` is created and published automatically by the release workflow so Homebrew bottles have a stable upload target. This command writes the curated notes onto that existing Release, falling back to creating it if it does not exist yet.
+## Publish Release Notes
 
 ```bash
-if gh release view "v{version}" >/dev/null 2>&1; then
-  gh release edit "v{version}" --notes-file "{notes-file}"
-else
-  gh release create "v{version}" --title "v{version}" --notes-file "{notes-file}"
-fi
+agent-infra-internal platform-release-notes publish \
+  --tag "v{version}" --title "v{version}" --notes-file "{notes-file}"
 ```
 
-If commands fail, stop or escalate according to the calling skill.
+The command updates an existing Release or creates a missing one. `--dry-run` only plans the operation. Exit codes `0/1/2` mean success, failure, and blocked.

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

@@ -1,52 +1,22 @@
 # Release 平台命令
 
-在读取历史 release、查询已合并 PR，或发布 Release notes 前先读取本文件。
+发布说明平台操作统一使用 typed internal intent。调用方只解释结构化 JSON，不解析平台命令、原始字段、身份邮箱规则或认证错误。
 
-## Release 查询
+## 收集发布说明上下文
 
 ```bash
-gh release list --limit {limit} --json tagName,isDraft,isPrerelease
-gh release view "{tag}" --json body,url
+agent-infra-internal platform-release-notes context \
+  --from-tag "v{prev-version}" --to-tag "v{version}" \
+  --branch "{branch}" --history-limit 3
 ```
 
-## 已合并 PR 查询
-
-```bash
-gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels
-```
-
-必要时读取关联 Issue：
-
-```bash
-gh issue view {issue-number} --json number,title,labels,url
-```
-
-## Contributor 映射辅助规则
-
-release notes 需要 contributors 时，已合并 PR 查询应包含 author：
-
-```bash
-gh pr list --state merged --base "{branch}" --json number,title,mergedAt,labels,author
-```
-
-关联 Issue 用于 reporter 归因时，查询应包含 author：
-
-```bash
-gh issue view {issue-number} --json number,title,labels,url,author
-```
-
-GitHub no-reply 邮箱映射规则：如果 `Name <email>` 中的 email 匹配 `(\d+\+)?(\S+?)@users\.noreply\.github\.com`，使用第二个捕获组的小写形式作为 login。该规则同时覆盖 `{id}+{login}@users.noreply.github.com` 和 `{login}@users.noreply.github.com`。
+结果包含历史发布、PR、关联 Issue 和规范化贡献者身份。不支持的平台返回稳定的 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op。
 
 ## 发布 Release notes
 
-`v{version}` 的 GitHub Release 由 release 工作流自动创建并发布，为 Homebrew bottle 提供稳定的上传落点。本命令把精修后的 notes 写到这个已存在的 Release 上；若 Release 尚不存在则兜底创建。
-
 ```bash
-if gh release view "v{version}" >/dev/null 2>&1; then
-  gh release edit "v{version}" --notes-file "{notes-file}"
-else
-  gh release create "v{version}" --title "v{version}" --notes-file "{notes-file}"
-fi
+agent-infra-internal platform-release-notes publish \
+  --tag "v{version}" --title "v{version}" --notes-file "{notes-file}"
 ```
 
-失败时按调用方规则停止或提示人工介入。
+命令更新既有 Release，缺失时创建；`--dry-run` 只规划操作。退出码 `0/1/2` 分别表示成功、失败和阻塞。

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

@@ -1,5 +1,5 @@
 # Release 命令
 
-当前代码平台未内置发布命令支持。
+当前代码平台未提供发布说明 adapter。
 
-自定义平台会跳过远端发布自动化，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和脚本。请继续使用本地发布产物或你的平台专属发布流程。
+调用 `agent-infra-internal platform-release-notes context` 会返回结构化的 `PLATFORM_RELEASE_NOTES_UNSUPPORTED` no-op，不得探测其他平台 client。在提供 adapter 前，发布操作同样保持 no-op。

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

@@ -62,26 +62,29 @@ The single source of truth for disagreement state is the fixed `## 审查分歧
 - `stage` ∈ `{analysis, plan, code}` (plus the reserved value `post-review-commit`, used only for post-review exemption rows).
 - `status` legal enum: `open` / `accepted` / `adjusted` / `refuted` / `cannot-judge` / `confirmed` / `needs-human-decision` / `closed` / `human-decided`.
 - **Terminal set (gate passes)**: `{confirmed, closed, human-decided}`; everything else is blocking.
-- **Write responsibility**: `review-*` raises a finding → upsert an `open` row; `*-task` responds → set four-state and fill `evidence`, `round` +1; next `review-*` → `confirmed` / back to `open` / `needs-human-decision`; an executor fix verified by the next review → `closed`; a human ruling → `human-decided`.
+- **Same-round fix-and-close**: only when the reviewer fixes a `minor` finding during the current review round may `finding-review` move that row directly from `open` to `closed`. This transition does not increment `round`, and `evidence` must point to the fix in the current review artifact; it does not apply to `blocker` or `major` findings.
+- **Severity is independent from advancement**: `blocker` / `major` / `minor` express impact only. Every formal finding blocks approval until terminal. After all writes, review verdicts, event counts, and next steps must be derived from `task-ledger stage-status --stage {stage}`.
+- **Non-blocking advisories**: only future optimizations that do not affect the current artifact's completeness, correctness, or acceptance. Advisories stay in a separate report section and never enter this ledger, finding counts, or verdict; manual-validation remains a separate category.
+- **Write responsibility**: callers submit structured intents only; they do not scan ids, assemble table rows, or decide mechanical transitions. `review-*` uses `agent-infra-internal task-ledger {task-id} finding-upsert|finding-review ...`; `*-task` uses `finding-respond ...`; `ai decide` applies human rulings atomically. The core validates and commits each intent through one task write.
 - **Backward compatible**: when task.md has no such section the gate treats it as no open disagreements and passes.
 
 ### Executor-raised human-ruling rows
 
-When an executor judges an item to be a key design decision that needs human ruling, it must write the detail block (background / options / impact / recommendation) into the artifact's `## 人工裁决待办` (Pending Human Decisions) section with a heading like `### HD-N：<title> [needs-human-decision]`, and upsert the matching `HD-` row in task.md `## Review Disagreement Ledger`:
+When an executor judges an item to be a key design decision that needs human ruling, it must 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]`, and upsert the matching `HD-` row in task.md `## Review Disagreement Ledger`:
 
 ```markdown
 | HD-1 | plan | - | decision | needs-human-decision | plan.md#HD-1 |
 ```
 
-- `id`: the `HD-N` number is **globally unique**. When adding a row, scan every `HD-(\d+)` in the ledger and take max+1 (start at `HD-1` when none exist); it increases monotonically across `analysis` / `plan` / `code` and is **never reused**, so selecting by `HD-id` is unambiguous.
+- `id`: the `HD-N` number is **globally unique**. First run `agent-infra-internal task-ledger {task-id} decision-next-id` and read `entityId`; after writing the stable artifact heading, run `decision-upsert --id {HD-N} --stage {stage} --artifact {artifact}`. The model must not scan or allocate ids.
 - `stage` is the stage where the decision arose: `analysis` / `plan` / `code`.
 - `round` is `-` because this is not a review-finding handshake round.
 - `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.
-- After a human records the ruling in task.md `## Human Rulings`, flip the matching `HD-` row to `human-decided` and point `evidence` to that ruling.
+- 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.
 
-> View: `ai task decisions <task-ref>` lists all pending decisions; `ai task decisions <task-ref> <ordinal|HD-id>` expands a single item's detail block. This command shares the ledger parser `lib/task/ledger.ts` with `ai task log`; the gate parser in `.agents/scripts/validate-artifact.js` is a separate implementation and the two must be kept semantically in sync by hand.
+> Viewing, deciding, and typed verification share the `lib/task/ledger.ts` domain semantics.
 
 ## post-review commit gate (code stage only)
 
@@ -89,7 +92,8 @@ When an executor judges an item to be a key design decision that needs human rul
 - `commit` reads only the highest-round Approved `review-code` artifact. Before committing it requires `pre_head == R`, complete worktree tree `W == T`, and normalized staged tree `S == T`; any mismatch blocks before `git commit` and reports added, missing, and different paths for both comparisons.
 - After a successful commit it sets `B=last_reviewed_commit=<new_head>`; B means only a reviewed snapshot anchored to a Git commit.
 - The `complete-task` `post-review-commit` gate uses only B. When B is absent, malformed, or missing as a Git object, it reports `reviewed snapshot was not anchored` and never falls back to R.
-- If new commits touch code / rule paths after B, the gate blocks and requires a fresh `review-code`.
+- If new commits touch code / rule paths after B, the gate blocks and requires a fresh `review-code`. The only automatic exception is a bound merged GitHub PR whose platform snapshot proves B is the original PR head, whose merge commit is in local HEAD history, whose reviewed changes exactly match the normalized patch of a single-parent squash commit, and whose protected paths have no later commits. Missing platform or Git evidence fails closed.
+- Required checks remain a pre-merge responsibility of branch protection / rulesets and the `review-code` / `watch-pr` routes. The post-review-commit gate still applies the strict / squash-equivalent relation above independently.
 - **Exemption**: append a ledger row `| PRC-1 | post-review-commit | - | - | human-decided | <ruling note> |` recording that a human explicitly allowed those commits without re-review.
 
 ## Gate behavior cheat sheet

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

@@ -62,26 +62,29 @@
 - `stage` ∈ `{analysis, plan, code}`（外加保留值 `post-review-commit`，仅用于 post-review 豁免行）。
 - `status` 合法枚举：`open` / `accepted` / `adjusted` / `refuted` / `cannot-judge` / `confirmed` / `needs-human-decision` / `closed` / `human-decided`。
 - **终态集合（gate 放行）**：`{confirmed, closed, human-decided}`；其余为阻塞态。
-- **写入责任**：`review-*` 提 finding → upsert `open` 行；`*-task` 响应 → 改四态并填 `evidence`、`round` +1；下一轮 `review-*` → `confirmed` / 置回 `open` / `needs-human-decision`；执行方修复经下一轮 review 验证通过 → `closed`；人工裁决 → `human-decided`。
+- **同轮 fix-and-close**：仅当检视方在当前审查轮当场修复 `minor` finding 时，可通过 `finding-review` 将该行从 `open` 直接置为 `closed`。此转换不增加 `round`，`evidence` 必须指向当前 review 产物中的修复证据；`blocker` / `major` 不适用。
+- **severity 与推进解耦**：`blocker` / `major` / `minor` 只表示影响大小。任何正式 finding 只要尚未进入终态就阻止当前阶段通过；review 结论、事件计数与下一步必须在全部写入后通过 `task-ledger stage-status --stage {stage}` 从同一语义导出。
+- **非阻塞 advisory**：仅限不影响当前产物完整性、正确性和验收的后续优化。advisory 只写入报告的独立段落，不进入本账本、不进入 finding 计数、不影响 verdict；manual-validation 仍是独立分类。
+- **写入责任**：调用方只提交结构化意图，不扫描编号、不拼表格行、不自行判断机械状态迁移。`review-*` 用 `agent-infra-internal task-ledger {task-id} finding-upsert|finding-review ...`；`*-task` 用 `finding-respond ...`；人工裁决由 `ai decide` 原子完成。核心统一校验并通过一次任务写入提交。
 - **向后兼容**：task.md 无此段时，gate 视为无未决分歧而放行。
 
 ### 执行方自提人工裁决行
 
-当执行方判定某项为需人工裁定的关键设计决策时，必须把详情块（背景 / 选项 / 影响 / 推荐）写入产物的 `## 人工裁决待办` 段，标题形如 `### HD-N：<标题> [needs-human-decision]`，并在 task.md `## 审查分歧账本` upsert 对应 `HD-` 行：
+当执行方判定某项为需人工裁定的关键设计决策时，必须按 `.agents/rules/human-decision-context.md` 把自足详情块写入产物的 `## 人工裁决待办` 段，标题形如 `### HD-N：<标题> [needs-human-decision]`，并在 task.md `## 审查分歧账本` upsert 对应 `HD-` 行：
 
 ```markdown
 | HD-1 | plan | - | decision | needs-human-decision | plan.md#HD-1 |
 ```
 
-- `id`：`HD-N` 编号**全局唯一**。新增行时扫描账本中所有 `HD-(\d+)`，取最大值 + 1（账本无 `HD-` 行则从 `HD-1` 起）；跨 `analysis` / `plan` / `code` 单调递增，**禁止复用**既有编号，避免按 `HD-id` 定位时歧义。
+- `id`：`HD-N` 编号**全局唯一**。先调用 `agent-infra-internal task-ledger {task-id} decision-next-id` 取得 `entityId`，产出稳定标题后调用 `decision-upsert --id {HD-N} --stage {stage} --artifact {artifact}`；不得由模型扫描或分配编号。
 - `stage` 填该决策产生的阶段：`analysis` / `plan` / `code`。
 - `round` 填 `-`，因为它不是 review finding 的握手轮次。
 - `severity` 固定填 `decision`。
 - `status` 初始填 `needs-human-decision`，因此会被现有 gate 阻塞。
 - `evidence` 指向稳定锚点 `<artifact>#HD-N`（如 `plan-r2.md#HD-1`），不依赖易漂移的行号。
-- 人工在 task.md `## 人工裁决` 段记录裁定后，把对应 `HD-` 行翻为 `human-decided`，`evidence` 指向该裁定记录。
+- 人工使用 `ai decide <task-ref> <序号|账本ID> <裁决内容>` 记录裁定；命令把目标行翻为 `human-decided`，并让 `evidence` 指向独立 `HDR-N` 裁定记录。
 
-> 查看：`ai task decisions <task-ref>` 列出全部待裁决项；`ai task decisions <task-ref> <序号|HD-id>` 展开单项详情块。该命令的账本解析与 `ai task log` 共用 `lib/task/ledger.ts`；`.agents/scripts/validate-artifact.js` 的 gate 解析器是独立实现，二者语义须手工保持同步。
+> 查看、裁决与 typed verification 共用 `lib/task/ledger.ts` 的领域语义。
 
 ## post-review commit 门禁（仅 code 阶段）
 
@@ -89,7 +92,8 @@
 - `commit` 只读取最高轮 Approved `review-code` 产物；提交前比较 `pre_head == R`、完整工作区树 `W == T`、规范化暂存树 `S == T`，任一失配都在 `git commit` 前阻断并报告两组 added/missing/different 路径。
 - 成功提交后令 `B=last_reviewed_commit=<new_head>`；`B` 只表示已经落到 Git commit 的审查锚点。
 - `complete-task` 的 `post-review-commit` gate 只使用 B；B 缺失、畸形或对象不存在时报告 `reviewed snapshot was not anchored`，不得回退 R。
-- 若 B 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。
+- 若 B 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。唯一自动例外是绑定 GitHub PR 已合并，且平台快照证明 B 是原 PR head、merge commit 位于本地 HEAD 历史中、受审查变更与单父 squash commit 的规范化补丁完全一致，并且 merge 后受保护路径没有新提交；缺少任一平台或 Git 证据时 fail closed。
+- required checks 由合并前的分支保护 / ruleset 与 `review-code` / `watch-pr` 路由负责。post-review-commit 仍独立执行上述严格 / squash 等价判定。
 - **豁免**：在账本追加一行 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`，记录人工明确允许该批提交免复审。
 
 ## gate 行为速查

package/templates/.agents/rules/task-management.en.md

@@ -19,6 +19,13 @@ Map user intent to the corresponding workflow command:
 - Before updating `agent_infra_version`, read `.agents/rules/version-stamp.md`
 - Activity Log entries are append-only and must never overwrite history
 
+## State Snapshot and Completion Verification Entrypoints
+
+- Runtime skills that record git, task-directory, and task.md tail evidence must call `agent-infra-internal task-snapshot {task-id} --format text`; they must not resolve short ids, scan workspaces, or reconstruct the three observations themselves.
+- Runtime skills that execute completion gates must call `agent-infra-internal task-verify {task-id} <verification-event> [--artifact <artifact>] --format text`; the typed verification catalog is the sole mapping from business event to skill, workspace, gate/check order, and artifact family.
+- `task-verify` executes the typed catalog/check registry in-process; skills declare business events only.
+- Both entrypoints are read-only. Verification exits remain `0=pass`, `1=fail`, and `2=blocked`; network or platform blocking must never be downgraded to success.
+
 ## Required State Updates by Command
 
 - `create-task`: create `branch`, `workflow`, `status`, `created_at`, `updated_at`, `assigned_to`, `agent_infra_version`
@@ -40,9 +47,11 @@ Map user intent to the corresponding workflow command:
 
 ## Activity Log started / done dual-marker convention (single source of truth)
 
-> This section is the sole authoritative definition of the started/done dual marker. The skills, the renderer (`lib/task/commands/log.ts`), and the validator (`.agents/scripts/validate-artifact.js`) all defer to it; keep this section in sync when changing any of them.
+`analyze-task`, `review-analysis`, `plan-task`, `review-plan`, `code-task`, and `review-code` must declare business events through `agent-infra-internal task-event`. The event core generates `current_step`, `assigned_to`, `updated_at`, `agent_infra_version`, and the log text below. Other lifecycle skills not yet migrated continue to follow this textual protocol.
+
+> This section is authoritative for skills, the renderer, and typed verification checks.
 
-**Line grammar is unchanged**: both started and done use the existing entry grammar `- {YYYY-MM-DD HH:mm:ss±HH:MM} — **{action}** by {agent} — {note}`, so the parsing regexes (`log.ts:ENTRY_RE` and `validate-artifact.js:ACTIVITY_LOG_PATTERN`) need no change.
+**Line grammar is unchanged** and shared by the log renderer and verification activity parser.
 
 - **started line** (written when the step begins): the action suffixes the existing base with ` [started]`, note is `started`:
   `- {time} — **{base} [started]** by {agent} — started`

package/templates/.agents/rules/task-management.zh-CN.md

@@ -19,6 +19,13 @@
 - 更新 `agent_infra_version` 前，先读取 `.agents/rules/version-stamp.md`
 - Activity Log 只能追加，不能覆盖历史记录
 
+## 状态快照与完成验证入口
+
+- 运行时 SKILL 需要记录 git、任务目录和 task.md tail 证据时，统一调用 `agent-infra-internal task-snapshot {task-id} --format text`；不得自行解析短号、扫描 workspace 或重新拼接三段状态命令。
+- 运行时 SKILL 需要执行完成门禁时，统一调用 `agent-infra-internal task-verify {task-id} <verification-event> [--artifact <artifact>] --format text`；业务事件到 skill、workspace、gate/check 顺序和产物族的映射由 typed verification catalog 唯一维护。
+- `task-verify` 在进程内执行 typed catalog/check registry；SKILL 只声明业务事件，不传 task-dir、skill 名或特殊 check 序列。
+- 两个入口均保持只读；验证退出码固定为 `0=pass`、`1=fail`、`2=blocked`，网络或平台阻塞不得降格为成功。
+
 ## 常见命令的状态更新要求
 
 - `create-task`：创建 `branch`、`workflow`、`status`、`created_at`、`updated_at`、`assigned_to`、`agent_infra_version`
@@ -40,12 +47,13 @@
 
 ## Activity Log started / done 双标记约定（单一事实源）
 
-> 本节是 started/done 双标记的唯一权威定义。各 SKILL、渲染器（`lib/task/commands/log.ts`）、
-> 校验脚本（`.agents/scripts/validate-artifact.js`）的相关行为都以本节为准；改动任一端时同步本节。
+`analyze-task`、`review-analysis`、`plan-task`、`review-plan`、`code-task`、`review-code` 必须通过 `agent-infra-internal task-event` 声明业务事件；事件核心统一生成 `current_step`、`assigned_to`、`updated_at`、`agent_infra_version` 和下述日志文本。其余尚未迁移的生命周期 SKILL 继续遵循本节文本协议。
+
+> 本节是 started/done 双标记的唯一权威定义。各 SKILL、渲染器与 typed verification check 都以本节为准。
 
 **行语法不变**：started 与 done 都沿用既有条目语法
 `- {YYYY-MM-DD HH:mm:ss±HH:MM} — **{action}** by {agent} — {note}`，因此解析正则
-（`log.ts:ENTRY_RE` 与 `validate-artifact.js:ACTIVITY_LOG_PATTERN`）无需改动。
+（`log.ts:ENTRY_RE` 与 verification activity parser）无需改动。
 
 - **started 行**（步骤开始时写）：action 在既有基名末尾加后缀 ` [started]`，note 用 `started`：
   `- {time} — **{基名} [started]** by {agent} — started`