@fitlab-ai/agent-infra 0.8.4 → 0.9.0

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/review-handshake.en.md

@@ -62,33 +62,37 @@ 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)
 
-- `review-code` captures `Review Baseline Commit` (R, `git rev-parse HEAD`) once, computes `Reviewed Diff Fingerprint` (F, the full worktree diff fingerprint) from that same R, and records both in the highest-round report. When the round is Approved it also writes `last_reviewed_commit: R` (B) to task.md; a non-Approved round preserves the existing B.
-- `commit` reads only the highest-round `review-code` artifact. When that artifact is Approved, the pre-commit HEAD equals R, and the staged diff fingerprint equals F, it advances task.md B to the new commit SHA.
-- The `complete-task` `post-review-commit` gate prefers B; when B is absent or invalid, it falls back to R from the highest-round `review-code` artifact.
-- If new commits touch code / rule paths after B / R, the gate blocks and requires a fresh `review-code`.
+- `review-code` captures the review baseline `R` (diff base), full-worktree diff fingerprint `F`, and normalized snapshot tree `T`. An Approved clean snapshot may set `B=R`; an Approved snapshot with uncommitted changes clears or omits `B`.
+- `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`.
 - **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,33 +62,37 @@
 - `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 阶段）
 
-- `review-code` 一次性捕获 `审查基线提交`（R，`git rev-parse HEAD`），以同一 R 计算 `审查差异指纹`（F，完整工作区 diff fingerprint）并写入最高轮报告；本轮 Approved 时同时在 task.md 写入 `last_reviewed_commit: R`（B），非 Approved 时保留既有 B。
-- `commit` 只读取最高轮 `review-code` 产物；当该产物 Approved、提交前 HEAD 等于 R、且 staged diff fingerprint 等于 F 时，把 task.md 的 B 推进为新提交 SHA。
-- `complete-task` 的 `post-review-commit` gate 优先使用 B；B 缺失或非法时回退最高轮 `review-code` 的 R。
-- 若 B / R 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。
+- `review-code` 一次性捕获审查基线 `R`（diff base）、完整工作区差异指纹 `F` 与规范化快照树 `T`；Approved 且快照干净时可令 `B=R`，Approved 且含未提交差异时清除/不写 `B`。
+- `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`。
 - **豁免**：在账本追加一行 `| 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`

package/templates/.agents/rules/task-short-id.en.md

@@ -1,36 +1,34 @@
 # Task short id
 
 Task short ids let mobile-style SKILL invocations replace the full 22-char
-`TASK-YYYYMMDD-HHMMSS` with bare numeric `N` (recommended) or `#NN` while a
-task is active.
+`TASK-YYYYMMDD-HHMMSS` with bare numeric `N` while a task is active.
 
 ## Syntax
 
-- Two equivalent literal forms are accepted:
-  - **Bare numeric `N`** (recommended; no shell quoting needed): e.g. `1`, `7`, `42`.
-  - **`#`-prefixed `#N` / `#NN`** (also accepted; bash needs `'...'` quoting): e.g. `#1`, `#01`, `#42`.
+- Only **bare numeric `N`** is accepted (no shell quoting needed): e.g. `1`, `7`, `42`.
 - Resolution: drop leading zeros and take the numeric value `n`; if `n == 0`,
   reject (reserved); if `n > 10^shortIdLength - 1`, reject (over capacity);
-  otherwise canonicalize to `#${n.padStart(shortIdLength, '0')}` as the
+  otherwise canonicalize to `${n.padStart(shortIdLength, '0')}` as the
   registry key.
 - With the default `shortIdLength=2`, capacity is `n ∈ [1, 99]`; registry keys
   look like `01`, `07`, `42`.
-- `#00` (or `#0` when `shortIdLength=1`) is reserved and never allocated; digits
+- `00` (or `0` when `shortIdLength=1`) is reserved and never allocated; digits
   only, no letters.
-- The plain `TASK-…` form keeps working everywhere; bare numeric / `#NN` is an
-  alias, not the persisted task id.
+- The plain `TASK-…` form keeps working everywhere; bare numeric is an alias,
+  not the persisted task id.
+- Removed `#N` / `#NN` syntax is consistently rejected as an invalid task ref.
 
 ## Lifecycle
 
 | Action     | When                                                                 | Effect on registry                                            |
 |------------|-----------------------------------------------------------------------|---------------------------------------------------------------|
-| alloc      | `create-task`, `import-issue`, `import-codescan`, `import-dependabot` | Assigns lowest free `#NN` in the registry.                    |
-| resolve    | Lifecycle SKILLs (`analyze-task`, `plan-task`, `code-task`, …)        | Looks up `#NN` → full task id. Does not allocate.             |
+| alloc      | `create-task`, `import-issue`, `import-codescan`, `import-dependabot` | Assigns lowest free `NN` in the registry.                    |
+| resolve    | Lifecycle SKILLs (`analyze-task`, `plan-task`, `code-task`, …)        | Looks up `NN` → full task id. Does not allocate.             |
 | release    | `complete-task`, `cancel-task`, `block-task`, `close-codescan`, `close-dependabot` | Removes the registry entry. |
-| re-alloc   | `restore-task`                                                        | Re-allocates a (possibly new) `#NN` in the registry. |
+| re-alloc   | `restore-task`                                                        | Re-allocates a (possibly new) `NN` in the registry. |
 
 Short ids are valid only while a task lives in `.agents/workspace/active/`.
-Once it is moved to `completed/`, `blocked/`, or `archive/`, the `#NN` slot is
+Once it is moved to `completed/`, `blocked/`, or `archive/`, the `NN` slot is
 freed and may be reused by a new task.
 
 ## Configuration
@@ -39,7 +37,7 @@ freed and may be reused by a new task.
 // .agents/.airc.json
 {
   "task": {
-    "shortIdLength": 2  // default; capacity = 99 (#01–#99). Set to 3 for #001–#999.
+    "shortIdLength": 2  // default; capacity = 99 (01–99). Set to 3 for 001–999.
   }
 }
 ```
@@ -49,12 +47,12 @@ error suggesting either archiving some tasks or raising `task.shortIdLength`.
 There is no silent extension or truncation. Changing `shortIdLength` requires
 archiving all active tasks first (the registry key width depends on it).
 
-## `#NN` resolution scope (split by entrypoint)
+## Short-id resolution scope (split by entrypoint)
 
 | Entrypoint                                                  | Hit                  | Miss                                                 |
 |-------------------------------------------------------------|----------------------|------------------------------------------------------|
 | SKILL parameter resolver (lifecycle SKILLs)                  | resolve to full id   | **strict error** — short id not found / invalid     |
-| `ai sandbox exec <N \| '#N'>` / `ai sandbox create <N \| '#N'>`           | resolve to full id, then read `branch` from task.md | **strict error** — no ls-index fallback, no literal-branch fallback; hint the user to pass a short id / `TASK-id` / branch name |
+| `ai sandbox exec <N>` / `ai sandbox create <N>`           | resolve to full id, then read `branch` from task.md | **strict error** — no ls-index fallback, no literal-branch fallback; hint the user to pass a short id / `TASK-id` / branch name |
 
 `list --verify` is strictly read-only: it reports discrepancies between the
 active dir and the registry, but never writes.
@@ -64,10 +62,10 @@ active dir and the registry, but never writes.
 Any SKILL (alloc / resolve / release / re-alloc lifecycle entry-points) that
 receives a `{task-id}` argument must follow this contract:
 
-1. If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric `N` or `#`-prefixed `#N`):
+1. If `{task-id}` matches `^[0-9]+$` (bare numeric `N`):
 
 ```bash
-if [[ "{task-id}" =~ ^[#]?[0-9]+$ ]]; then
+if [[ "{task-id}" =~ ^[0-9]+$ ]]; then
   # The script writes the full error message (covering reserved / exceeds
   # shortIdLength capacity / malformed input) to stderr; callers only forward
   # the exit.
@@ -102,7 +100,7 @@ Short ids are pure local state, persisted only in the registry
   registry entry is deleted immediately and the short id may be reused; archived
   tasks are referenced by their full `TASK-…` id.
 
-`resolve(<N|'#N'>)` workflow: ① validate arg matches `^[#]?[0-9]+$` →
+`resolve(<N>)` workflow: ① validate arg matches `^[0-9]+$` →
 ② strip leading zeros and take the numeric value `n`; classify as reserved
 (`n == 0`) / over capacity (`n > 10^shortIdLength - 1`) / normal → ③ on
 normal, use `n.padStart(shortIdLength, '0')` as the registry `ids` key
@@ -116,18 +114,16 @@ repair hint.
   wrong. Exit code 1.
 - **Registry corruption** (duplicate registry entries for the same task id, or
   the JSON is unparsable): exit code 2; manual cleanup required.
-- **Reserved key**: the resolved `n == 0` (inputs like `0`, `#0`, `#00`). Exit code 1.
+- **Reserved key**: the resolved `n == 0` (inputs like `0`, `00`). Exit code 1.
 - **Over capacity**: the resolved `n > 10^shortIdLength - 1` (e.g. `100` or
-  `#100` when `shortIdLength=2`). Exit code 1.
-- **Parameter format error**: input matches neither `^[#]?[0-9]+$` nor a
-  `TASK-id` (e.g. `#abc`, `#`, `5.5`). Exit code 1.
+  `100` when `shortIdLength=2`). Exit code 1.
+- **Parameter format error**: input matches neither `^[0-9]+$` nor a
+  `TASK-id` (e.g. `#1`, `#abc`, `#`, `5.5`). Exit code 1.
 
-## Cross-TUI quoting
+## Cross-TUI use
 
-Bare numeric `N` is safe in every shell and TUI without quoting (recommended):
+Bare numeric `N` is safe in every shell and TUI without quoting:
 `ai sandbox exec 11 'npm test'`, `/review-analysis 11`.
 
-The `#N` / `#NN` form is also accepted; but bash treats `#` as a comment
-marker, so it must be single-quoted: `ai sandbox exec '#03' 'npm test'`.
-Claude Code / Codex / Gemini CLI / OpenCode all forward `#NN` to SKILL
-`ARGUMENTS` literally when quoted.
+Starting with the next major version, migrate the old `#NN` form to `NN`;
+even a quoted value delivered intact to the CLI is rejected.

package/templates/.agents/rules/task-short-id.zh-CN.md

@@ -1,25 +1,24 @@
 # 任务短号
 
-短号让所有 SKILL 在 active 任务生命周期内可以用 `#NN` 或裸数字 `N`（推荐）替代
+短号让所有 SKILL 在 active 任务生命周期内可以用裸数字 `N` 替代
 完整的 22 字符 `TASK-YYYYMMDD-HHMMSS`。
 
 ## 语法
 
-- 字面接受两种等价形式：
-  - **裸数字 `N`**（推荐，无需 shell 引号）：如 `1`、`7`、`42`。
-  - **`#`-前缀 `#N` / `#NN`**（也接受；但 bash 需 `'...'` 引号）：如 `#1`、`#01`、`#42`。
+- 只接受**裸数字 `N`**（无需 shell 引号）：如 `1`、`7`、`42`。
 - 解析规则：去前导零后取数值 `n`，若 `n == 0` 报错（保留）；若 `n > 10^shortIdLength - 1`
-  报错（超容量）；否则归一化为 `#${n.padStart(shortIdLength, '0')}`，作为注册表 key。
+  报错（超容量）；否则归一化为 `${n.padStart(shortIdLength, '0')}`，作为注册表 key。
 - 默认 `shortIdLength=2` 时容量 `n ∈ [1, 99]`，注册表 key 形如 `01`、`07`、`42`。
-- `#00`（或 `shortIdLength=1` 时 `#0`）保留、永不分配；纯数字、不引入字母。
-- 完整 `TASK-…` 入参在所有路径下行为与现状等价；`#NN` / 裸数字只是别名，不是持久化任务 ID。
+- `00`（或 `shortIdLength=1` 时 `0`）保留、永不分配；纯数字、不引入字母。
+- 完整 `TASK-…` 入参在所有路径下行为与现状等价；裸数字只是别名，不是持久化任务 ID。
+- 已移除的 `#N` / `#NN` 语法作为无效任务引用稳定拒绝。
 
 ## 生命周期
 
 | 动作      | 触发时机                                                                                     | 注册表效应                                                       |
 |-----------|---------------------------------------------------------------------------------------------|------------------------------------------------------------------|
-| alloc     | `create-task`、`import-issue`、`import-codescan`、`import-dependabot`                       | 分配最小可用 `#NN`，写入注册表。                                  |
-| resolve   | 生命周期 SKILL（`analyze-task` / `plan-task` / `code-task` / `review-*` / `commit` / …）    | `#NN` → 完整 task id 查询，不分配。                              |
+| alloc     | `create-task`、`import-issue`、`import-codescan`、`import-dependabot`                       | 分配最小可用 `NN`，写入注册表。                                  |
+| resolve   | 生命周期 SKILL（`analyze-task` / `plan-task` / `code-task` / `review-*` / `commit` / …）    | `NN` → 完整 task id 查询，不分配。                              |
 | release   | `complete-task`、`cancel-task`、`block-task`、`close-codescan`、`close-dependabot`          | 从注册表移除。                                                   |
 | re-alloc  | `restore-task`                                                                              | 重新分配（可能与历史不同），写入注册表。                         |
 
@@ -32,7 +31,7 @@
 // .agents/.airc.json
 {
   "task": {
-    "shortIdLength": 2  // 默认；容量 = 99（#01–#99）。改为 3 时容量 = #001–#999。
+    "shortIdLength": 2  // 默认；容量 = 99（01–99）。改为 3 时容量 = 001–999。
   }
 }
 ```
@@ -41,12 +40,12 @@
 `task.shortIdLength`」两种修复路径；不静默扩位、不静默截断。
 切换 `shortIdLength` 配置需要先归档所有 active 任务（注册表 key 宽度依赖配置）。
 
-## `#NN` 解析作用域（按入口二分）
+## 短号解析作用域（按入口二分）
 
 | 入口                                                       | 注册表命中            | 注册表未命中                                            |
 |-----------------------------------------------------------|----------------------|--------------------------------------------------------|
 | SKILL 入参解析器（生命周期 SKILL）                          | 解析为完整 task id    | **严格报错** —— 短号不存在 / 格式错误                  |
-| `ai sandbox exec <N \| '#N'>` / `ai sandbox create <N \| '#N'>`           | 解析为完整 task id 后查 task.md 取 `branch` | **严格报错** —— 不再回退到 ls 行号或字面分支名；提示用任务短号 / `TASK-id` / 分支名 |
+| `ai sandbox exec <N>` / `ai sandbox create <N>`           | 解析为完整 task id 后查 task.md 取 `branch` | **严格报错** —— 不再回退到 ls 行号或字面分支名；提示用任务短号 / `TASK-id` / 分支名 |
 
 `list --verify` 严格只读：报告 active 目录 / 注册表 两者差异，但不修改任何状态。
 
@@ -55,10 +54,10 @@
 任意 SKILL（含 alloc / resolve / release / re-alloc 四类生命周期入口）在收到
 `{task-id}` 入参后，必须按以下契约处理：
 
-1. 如果 `{task-id}` 字面匹配 `^[#]?[0-9]+$`（裸数字 `N` 或 `#`-前缀 `#N`）：
+1. 如果 `{task-id}` 字面匹配 `^[0-9]+$`（裸数字 `N`）：
 
 ```bash
-if [[ "{task-id}" =~ ^[#]?[0-9]+$ ]]; then
+if [[ "{task-id}" =~ ^[0-9]+$ ]]; then
   # 脚本本身已输出完整错误（含 reserved / exceeds shortIdLength capacity 等场景）；
   # 调用方只需透传退出码
   task_id=$(node .agents/scripts/task-short-id.js resolve "{task-id}") || exit 1
@@ -82,7 +81,7 @@ fi
 - 短号只由显式 `alloc`（`create-task` / `import-*` / `restore-task`）分配；`resolve` / `list` / `release` 不分配，仅在执行时自动清理指向非 active 任务的 stale entry
 - 归档（complete-task / cancel-task / block-task / close-*）后注册表 entry 立即删除，短号可被新任务复用；归档后引用任务一律用完整 `TASK-…` id
 
-`resolve(<N|'#N'>)` 工作流：① 校验入参匹配 `^[#]?[0-9]+$` → ② 去前导零取
+`resolve(<N>)` 工作流：① 校验入参匹配 `^[0-9]+$` → ② 去前导零取
 数值 `n`，按 `n` 是否 `== 0`（保留）/ `> 10^shortIdLength - 1`（超容量）/
 正常 三类处理 → ③ 正常时以 `n.padStart(shortIdLength, '0')` 作为 key 查
 注册表 `ids` → ④ 命中返回完整 task id，未命中按 `list --verify` 给出修复指引退出 1。
@@ -91,15 +90,13 @@ fi
 
 - **短号不存在**：注册表中无对应 key。可能是任务已归档（短号已释放）或输入错误。退出码 1。
 - **注册表损坏**（同一 taskId 出现多次或 JSON 无法解析）：退出码 2，需人工处理。
-- **保留键**：解析后 `n == 0`（输入如 `0`、`#0`、`#00`）。退出码 1。
-- **超容量**：解析后 `n > 10^shortIdLength - 1`（如 `shortIdLength=2` 下 `100` 或 `#100`）。退出码 1。
-- **参数格式错误**：入参既不是 `^[#]?[0-9]+$` 也不是 `TASK-id`（如 `#abc`、`#`、`5.5`）。退出码 1。
+- **保留键**：解析后 `n == 0`（输入如 `0`、`00`）。退出码 1。
+- **超容量**：解析后 `n > 10^shortIdLength - 1`（如 `shortIdLength=2` 下 `100`）。退出码 1。
+- **参数格式错误**：入参既不是 `^[0-9]+$` 也不是 `TASK-id`（如 `#1`、`#abc`、`#`、`5.5`）。退出码 1。
 
-## 跨 TUI 引号要求
+## 跨 TUI 使用
 
-裸数字 `N` 在所有 shell 与 TUI 中都安全无需引号，推荐写法：
+裸数字 `N` 在所有 shell 与 TUI 中都安全无需引号：
 `ai sandbox exec 11 'npm test'`、`/review-analysis 11`。
 
-`#N` / `#NN` 写法也接受；但 bash 中 `#` 是注释起始符，必须单引号：
-`ai sandbox exec '#03' 'npm test'`。Claude Code / Codex / Gemini CLI / OpenCode
-在加引号时都能把 `#NN` 字面传递到 SKILL 的 `ARGUMENTS`。
+从下一个大版本起，原 `#NN` 写法必须迁移为 `NN`；即使引用后完整传入 CLI 也会被拒绝。