@fitlab-ai/agent-infra 0.8.4 → 0.9.0

package/templates/.agents/skills/code-task/reference/report-template.en.md

@@ -10,6 +10,16 @@ Use this structure when creating `code.md` or `code-r{N}.md`.
 - **Implementation Round**: Round {code-round}
 - **Artifact File**: `{code-artifact}`
 
+## Implementation Input
+
+- **Mode**: {init / fix / decision}
+- **Plan Input**: `{plan-artifact}`
+- **Review Input**: `{review-artifact or N/A}`
+- **Decision Input**: `{implementation-input or N/A}`
+- **Ledger ID**: `{decision-id or N/A}`
+- **Decision Evidence**: `{decision-evidence or N/A}`
+- **Scope Summary**: {scope of this round's implementation input}
+
 ## State Check
 
 > Paste the raw state-check command output; each command starts with `$ `.
@@ -64,7 +74,7 @@ $ {command}
 
 ## Per-Finding Verification
 
-> Fix mode only; for an initial implementation write "(initial implementation this round, no review findings)". Read/Grep-verify each finding of the previous `review-code`, then dispose of it with one of the four states in `.agents/rules/review-handshake.md`; write the disposition and **commensurate evidence** back to the matching row in the task.md disagreement ledger (stage=code, round +1). Symmetric evidence: accepted/adjusted cite the fix `file:line`; refuted/cannot-judge cite counter-evidence `file:line` or raw command output.
+> Fix mode only; for an initial implementation write "(initial implementation this round, no review findings)". Read/Grep-verify every prior finding and submit its four-state response through `task-ledger finding-respond`; do not edit the task.md table manually. accepted/adjusted cite the fix `file:line`; refuted/cannot-judge cite counter-evidence or raw command output.
 
 | Finding | Disposition | Commensurate evidence |
 |------|----------|----------|

package/templates/.agents/skills/code-task/reference/report-template.zh-CN.md

@@ -10,6 +10,16 @@
 - **实现轮次**: Round {code-round}
 - **产物文件**: `{code-artifact}`
 
+## 实现输入
+
+- **模式**：{init / fix / decision}
+- **方案输入**：`{plan-artifact}`
+- **审查输入**：`{review-artifact 或 N/A}`
+- **裁决输入**：`{implementation-input 或 N/A}`
+- **账本 ID**：`{decision-id 或 N/A}`
+- **裁决证据**：`{decision-evidence 或 N/A}`
+- **需求摘要**：{本轮实现输入的范围摘要}
+
 ## 状态核对
 
 > 粘贴状态核对命令原文；每条命令以 `$ ` 开头。
@@ -64,7 +74,7 @@ $ {command}
 
 ## 对审查发现的逐条核实
 
-> 仅修复模式填写；初次实现写「（本轮为初次实现，无审查发现）」。对上一轮 `review-code` 的每条发现先 Read/Grep 核实，再按 `.agents/rules/review-handshake.md` 的四态处置；并把处置与**相称证据**回写 task.md `## 审查分歧账本` 对应行（stage=code，round +1）。对称证据：accepted/adjusted 附修复点 file:line，refuted/cannot-judge 附反证 file:line 或命令原文。
+> 仅修复模式填写；初次实现写「（本轮为初次实现，无审查发现）」。对上一轮 `review-code` 的每条发现先 Read/Grep 核实，再按四态处置；相称证据完成后通过 `task-ledger finding-respond` 提交结构化意图，不手写 task.md 表格。accepted/adjusted 附修复点 file:line，refuted/cannot-judge 附反证 file:line 或命令原文。
 
 | 发现 | 处置状态 | 相称证据 |
 |------|----------|----------|

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

@@ -19,9 +19,11 @@ When updating related `task.md` frontmatter, read `.agents/rules/version-stamp.m
 | "`git add -A` is faster." | `git add -A` and `git add .` are forbidden; stage only explicitly listed files to avoid including unrelated changes. |
 | "This file has a copyright header, but the year can wait." | If you changed it, update the copyright year using `date +%Y`; this is a hard pre-commit check. |
 
-## Task id short ref
+## Task Context Resolution
 
-> If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
+> The entry point may omit the task ref and also accepts a legacy positional ref or `--task <ref>` / `-t <ref>`. Separate task scope from the full arguments while preserving every business operand, then call `agent-infra-internal task-context resolve {task-scope}` where `{task-scope}` is empty, one positional ref, or one task flag. Read only `taskId` from the structured result and bind `{task-id}` to that full `TASK-YYYYMMDD-HHMMSS` for downstream commands. Pass through resolution failures without scanning tasks locally.
+
+Without explicit task scope, only `TASK_CONTEXT_NOT_FOUND` may continue through the existing bare-commit path. Detached HEAD, damaged candidates, or multiple matches are ambiguity errors. Any explicit task-scope failure is fatal.
 
 ## Step Start: Write the started Marker
 
@@ -58,17 +60,19 @@ Review status, diff, and recent history, then prepare a Conventional Commit with
 
 ## 4. Create the Commit
 
-Stage specific files only and run `git commit` with the prepared message.
+Detect the restricted push-only scenario first. Otherwise write message, explicit paths, and expected HEAD/tree to JSON and call `agent-infra-internal git-workflow commit --input {file}`.
 
 If this commit is associated with a task and a `review-code` artifact exists, read the highest-round `review-code` artifact before committing:
-- If that artifact's `Overall Verdict` / `总体结论` is Approved, parse `Review Baseline Commit` / `审查基线提交` as `R`, and `Reviewed Diff Fingerprint` / `审查差异指纹` as `F`
-- After staging the explicit files, run `node .agents/scripts/review-diff-fingerprint.js staged <R>` to get `S`, and record `pre_head=$(git rev-parse HEAD)`
-- After committing, write `last_reviewed_commit: <new_head>` to task.md frontmatter only when `pre_head == R` and `S == F`; otherwise do not advance that field
+- If that artifact's `Overall Verdict` / `总体结论` is Approved, parse `R`, `F`, and `Reviewed Snapshot Tree` / `审查快照树` (`T`)
+- After staging the explicit files, record `pre_head=$(git rev-parse HEAD)` and use the helper's JSON mode to generate the complete worktree tree `W` and normalized staged tree `S`
+- Before `git commit`, require `pre_head == R && W == T && S == T`; use the helper's `compare` mode to produce added, missing, and different diagnostics for both worktree and staged snapshots
+- If any condition fails, enter Scenario 4 in `reference/task-status-update.md`; do not run `git commit`, push, successful state updates, PR summary sync, or the completion gate
+- After all comparisons match and the commit succeeds, write `last_reviewed_commit: <new_head>` to task.md frontmatter
 - Do not scan backward to earlier Approved artifacts; the highest-round `review-code` artifact is the only authoritative source
 
 ## 5. Push to the Existing PR When Applicable
 
-After the commit is created, if the current branch already has an open Pull Request, push the new commit so the PR updates automatically. Otherwise keep the current behavior (the first push is still handled by `create-pr`). This is the push wrap-up of a user-initiated `commit`: it adds no extra commit and never pushes when there is no PR; it applies whether or not a task is associated.
+After a new commit is created, or when Step 4 selects push-only, push HEAD normally if the current branch already has an open Pull Request. Otherwise keep the current behavior (the first push is still handled by `create-pr`). This adds no extra/empty commit and never pushes when there is no PR.
 
 > Detect whether the current branch has an open PR — and authenticate to the platform — per `.agents/rules/issue-pr-commands.md`; if that rule is unavailable or detection fails, follow the degradation below.
 
@@ -76,9 +80,7 @@ a. Detect whether the current branch (head) has an open PR per `.agents/rules/is
 
 b. On an open PR -> push the current branch:
 
-```bash
-git push
-```
+Use `agent-infra-internal git-workflow push --input {file}` for per-ref normal push and verification. Never force push.
 
 c. Safe degradation (never block an already completed `git commit`; only warn the user):
    - Platform unavailable / unauthenticated / detection failed / no open PR -> do not push; continue.
@@ -94,11 +96,13 @@ Get the current time:
 date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 ```
 
-> The full four-case status matrix, prerequisite checks, and multi-TUI next-step commands live in `reference/task-status-update.md`. Read `reference/task-status-update.md` before updating task state.
+> The full five-case status matrix, prerequisite checks, and multi-TUI next-step commands live in `reference/task-status-update.md`. Read `reference/task-status-update.md` before updating task state.
 
-> **IMPORTANT**: When showing the next step, output every TUI command format in full and directly use the standard template from `reference/task-status-update.md`. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+> **IMPORTANT**: When showing the next step, output every TUI command format in full and directly use the standard template from `reference/task-status-update.md`. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
 
 Append the Commit Activity Log entry and choose exactly one next-step case:
+- open PR and successful push -> `watch-pr {task-ref}`; this takes precedence over the final-commit `prFlow` route
+- failed push -> keep the task active and show only push/synchronization diagnostics; do not show `watch-pr` or `complete-task`
 - final commit -> render the next step by `.agents/.airc.json`'s `prFlow` (`disabled` -> single option `complete-task`; `required` -> single option `create-pr`; absent -> two options `create-pr` / `complete-task`); see Case 1 in `reference/task-status-update.md`
 - more work remains -> update task.md and stop
 - ready for review -> `review-code {task-id}`
@@ -107,7 +111,7 @@ Append the Commit Activity Log entry and choose exactly one next-step case:
 
 When `{task-id}` exists and task.md contains a valid `issue_number`, sync the linked Issue `in:` labels and requirement checkboxes. Otherwise, skip this step.
 
-> Trigger conditions, `in:` label computation rules, and requirement-checkbox sync flow live in `reference/issue-metadata-sync.md`. Read that file before running this step.
+> Trigger conditions and the declarative `platform-issue` call live in `reference/issue-metadata-sync.md`. Read that file before running this step.
 >
 > If this step touches the code-hosting platform, complete the prerequisite checks in `.agents/rules/issue-pr-commands.md` first.
 
@@ -128,7 +132,7 @@ Failure handling matches "Update Task Status When Applicable": warn, but do **no
 If this operation is associated with `{task-id}`, run the verification gate to confirm task metadata and sync state. If there is no task context, skip this step.
 
 ```bash
-node .agents/scripts/validate-artifact.js gate commit .agents/workspace/active/{task-id}
+agent-infra-internal task-verify {task-id} commit.completed --format text
 ```
 
 Handle the result as follows:

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

@@ -19,9 +19,11 @@ description: >
 | 「`git add -A` 更省事」 | 禁止 `git add -A`/`git add .`；只暂存明确列出的文件，避免带入无关改动。 |
 | 「改了带版权头的文件，年份先不动」 | 改了就更新版权年份（动态取 `date +%Y`），这是提交前的硬性检查。 |
 
-## 任务入参短号别名
+## 任务上下文解析
 
-> 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
+> 入口允许省略 task ref，也接受旧位置 task ref 或 `--task <ref>` / `-t <ref>`。先从完整参数中分离 task scope 并原样保留其他业务操作数，再调用 `agent-infra-internal task-context resolve {task-scope}`；`{task-scope}` 为空、位置 ref 或 task flag 之一。只读取结构化结果的 `taskId`，后续把 `{task-id}` 绑定为该完整 `TASK-YYYYMMDD-HHMMSS`。解析失败时透传非零退出码，不自行扫描任务。
+
+未显式指定 task scope 时，只有 `TASK_CONTEXT_NOT_FOUND` 可继续既有纯提交路径；detached HEAD、损坏候选或多匹配属于歧义，必须失败。显式 task scope 解析失败时一律失败。
 
 ## 步骤开始：写入 started 标记
 
@@ -58,17 +60,19 @@ git diff
 
 ## 4. 创建提交
 
-只暂存明确列出的文件，然后执行 `git commit`。
+先判断受限 push-only 场景；否则把 message、显式路径、expected HEAD/tree 写入临时 JSON，并调用 `agent-infra-internal git-workflow commit --input {file}`。core 负责范围、敏感文件、暂存树和幂等校验。
 
 如果本次提交关联任务且存在 `review-code` 产物，在提交前读取最高轮 `review-code` 产物：
-- 若该产物 `总体结论` / `Overall Verdict` 为 Approved，解析 `审查基线提交` / `Review Baseline Commit` 为 `R`，解析 `审查差异指纹` / `Reviewed Diff Fingerprint` 为 `F`
-- 暂存明确文件后运行 `node .agents/scripts/review-diff-fingerprint.js staged <R>` 得到 `S`，并记录 `pre_head=$(git rev-parse HEAD)`
-- 提交后仅当 `pre_head == R` 且 `S == F` 时，在 task.md frontmatter 写入 `last_reviewed_commit: <new_head>`；否则不推进该字段
+- 若该产物 `总体结论` / `Overall Verdict` 为 Approved，解析 `R`、`F` 与 `审查快照树` / `Reviewed Snapshot Tree`（`T`）
+- 暂存明确文件后记录 `pre_head=$(git rev-parse HEAD)`，并以 helper 的 JSON 模式生成当前完整工作区树 `W` 与规范化暂存树 `S`
+- 在 `git commit` 前要求 `pre_head == R && W == T && S == T`；分别运行 helper 的 `compare` 模式生成 worktree/staged 的 added、missing、different 路径诊断
+- 任一条件不满足时进入 `reference/task-status-update.md` 的“场景 4：提交前快照阻断”，不得执行 `git commit`、push、成功状态更新、PR 摘要同步或完成 gate
+- 全部相等并成功提交后，在 task.md frontmatter 写入 `last_reviewed_commit: <new_head>`
 - 不向后扫描更早的 Approved 产物；最高轮 `review-code` 产物是唯一权威来源
 
 ## 5. 推送到已有 PR（按需）
 
-提交完成后，如果当前分支已存在开放的 Pull Request，则把本次提交推送上去让 PR 自动更新；否则保持现状（首次推送仍由 `create-pr` 负责）。本步骤是用户已发起 `commit` 的推送收尾，不新增自动提交，也不在无 PR 时推送；与是否关联任务无关。
+新提交完成或步骤 4 命中 push-only 后，如果当前分支已存在开放的 Pull Request，则把 HEAD 普通推送上去让 PR 自动更新；否则保持现状（首次推送仍由 `create-pr` 负责）。本步骤不创建额外/空 commit，也不在无 PR 时推送；与是否关联任务无关。
 
 > 检测当前分支是否有开放 PR、以及平台认证，统一按 `.agents/rules/issue-pr-commands.md` 执行；该规则不可用或检测失败时，按下方降级处理。
 
@@ -76,9 +80,7 @@ a. 按 `.agents/rules/issue-pr-commands.md` 检测当前分支（head）是否
 
 b. 命中开放 PR -> 推送当前分支：
 
-```bash
-git push
-```
+通过 `agent-infra-internal git-workflow push --input {file}` 逐 ref 普通推送并复核，禁止 force push。
 
 c. 安全降级（不阻塞已完成的 `git commit`，仅提示用户）：
    - 平台不可用 / 未认证 / 检测失败 / 未命中开放 PR -> 不推送，继续后续步骤。
@@ -94,11 +96,13 @@ c. 安全降级（不阻塞已完成的 `git commit`，仅提示用户）：
 date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 ```
 
-> 完整的 4 种状态分支、前置条件检查和多 TUI 下一步命令见 `reference/task-status-update.md`。更新任务状态前，先读取 `reference/task-status-update.md`。
+> 完整的 5 种状态分支、前置条件检查和多 TUI 下一步命令见 `reference/task-status-update.md`。更新任务状态前，先读取 `reference/task-status-update.md`。
 
-> **重要**：向用户展示下一步时，必须完整输出所有 TUI 命令格式，并直接使用 `reference/task-status-update.md` 中对应场景的标准模板。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+> **重要**：向用户展示下一步时，必须完整输出所有 TUI 命令格式，并直接使用 `reference/task-status-update.md` 中对应场景的标准模板。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
 追加 Commit 的 Activity Log，并且只能选择一个下一步分支：
+- 已有开放 PR 且 push 成功 -> `watch-pr {task-ref}`；该分支优先于最终提交的 `prFlow` 路由
+- push 失败 -> 保持任务 active，只输出推送/同步诊断，不输出 `watch-pr` 或 `complete-task`
 - 最终提交 -> 按 `.agents/.airc.json` 的 `prFlow` 渲染下一步（`disabled` → 单选 `complete-task`；`required` → 单选 `create-pr`；缺省 → 二选一 `create-pr` / `complete-task`），详见 `reference/task-status-update.md` 场景 1
 - 还有后续工作 -> 更新 task.md 后停止
 - 准备审查 -> `review-code {task-id}`
@@ -107,7 +111,7 @@ date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 
 当 `{task-id}` 存在且 task.md 包含有效 `issue_number` 时，同步 `in:` label 和需求复选框到关联 Issue；否则跳过。
 
-> 触发条件、`in:` label 计算规则和复选框同步流程见 `reference/issue-metadata-sync.md`。执行前先读取该文件。
+> 触发条件与声明式 `platform-issue` 调用见 `reference/issue-metadata-sync.md`。执行前先读取该文件。
 >
 > 如果本步骤会访问代码托管平台，则先按 `.agents/rules/issue-pr-commands.md` 完成前置检测。
 
@@ -128,7 +132,7 @@ date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 如果本次操作关联了 `{task-id}`，运行完成校验，确认任务元数据和同步状态符合规范；如果没有任务上下文，跳过本步骤。
 
 ```bash
-node .agents/scripts/validate-artifact.js gate commit .agents/workspace/active/{task-id}
+agent-infra-internal task-verify {task-id} commit.completed --format text
 ```
 
 处理结果：

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

@@ -15,8 +15,7 @@
       ]
     },
     "activity-log": {
-      "expected_action_pattern": "Commit",
-      "freshness_minutes": 30
+      "expected_action_pattern": "Commit"
     },
     "platform-sync": {
       "when": "pr_number_exists",

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

@@ -40,17 +40,7 @@ Build the co-author block with these rules:
 ## Create the Commit
 
 ```bash
-git add <specific-files>
-git commit -m "$(cat <<'EOF'
-<type>(<scope>): <subject>
-
-- <bullet point 1>
-- <bullet point 2>
-
-Co-Authored-By: {Your Model Name} <noreply@provider.com>
-<additional Co-Authored-By lines>
-EOF
-)"
+agent-infra-internal git-workflow commit --input {commit-intent.json}
 ```
 
 Important:

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

@@ -40,17 +40,7 @@ git log --oneline -5
 ## 创建提交
 
 ```bash
-git add <specific-files>
-git commit -m "$(cat <<'EOF'
-<type>(<scope>): <subject>
-
-- <bullet point 1>
-- <bullet point 2>
-
-Co-Authored-By: {Your Model Name} <noreply@provider.com>
-<additional Co-Authored-By lines>
-EOF
-)"
+agent-infra-internal git-workflow commit --input {commit-intent.json}
 ```
 
 重要约束：

package/templates/.agents/skills/commit/reference/issue-metadata-sync.en.md

@@ -8,15 +8,11 @@ Run this step only when all of the following are true:
 
 If either condition is missing, skip this step.
 
-Read `.agents/rules/issue-sync.md` first so upstream repository detection and permission detection are complete before any sync work.
+Call one declarative intent. The internal core owns diff computation, repository-label filtering, capability degradation, body preservation, and idempotency:
 
-## `in:` Label Sync
-
-Follow the `in:` label sync steps in issue-sync.md and refine the Issue `in:` labels from the committed branch diff (`git diff {base-branch}...HEAD --name-only`).
-
-## Requirement Checkbox Sync
-
-Follow the requirement-checkbox sync steps in issue-sync.md and sync checked items from task.md `## Requirements` into the Issue body.
+```bash
+agent-infra-internal platform-issue sync {task-id} --agent {agent} --in-labels from-diff --base {base-branch} --requirements
+```
 
 ## Error Handling
 

package/templates/.agents/skills/commit/reference/issue-metadata-sync.zh-CN.md

@@ -8,15 +8,11 @@
 
 任一条件不满足时，跳过本步骤。
 
-执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测。
+调用单一声明式 intent；diff、仓库 label 过滤、权限降级、正文保真与幂等写入由 internal core 处理：
 
-## `in:` label 同步
-
-按 issue-sync.md 的 `in:` label 同步步骤，基于已提交分支的改动文件（`git diff {base-branch}...HEAD --name-only`）精修 Issue 的 `in:` label。
-
-## 需求复选框同步
-
-按 issue-sync.md 的需求复选框同步步骤，将 task.md `## 需求` 中已勾选的条目同步到 Issue body。
+```bash
+agent-infra-internal platform-issue sync {task-id} --agent {agent} --in-labels from-diff --base {base-branch} --requirements
+```
 
 ## 错误处理
 

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

@@ -1,21 +1,9 @@
-# Commit-Stage PR Summary Sync
+# Commit-stage PR Summary Synchronization
 
-> For the full aggregation rules, hidden marker, comment body template, PATCH/POST flow, shell safety constraints, and error handling, read `.agents/rules/pr-sync.md` before this step.
+Run only when `{task-id}` is valid and task.md has a valid `pr_number`.
 
-## Trigger Conditions
+1. Run `agent-infra-internal platform-pr summary-context {task-id}`.
+2. Generate the plain summary body per `.agents/rules/pr-sync.md` and write it to a temporary file.
+3. Run `agent-infra-internal platform-pr summary-sync {task-id} --agent {agent} --body-file {summary-body-file}`.
 
-Run this step only when both conditions are true:
-- `{task-id}` is valid
-- `task.md` frontmatter contains a valid `pr_number`
-
-If either condition is missing, skip PR summary sync and continue to verification.
-
-## Execution Notes
-
-- Generate or update the `<!-- sync-pr:{task-id}:summary -->` comment with the canonical template from `.agents/rules/pr-sync.md`
-- In this skill, PR summary sync failures are warnings only and must not block a completed `git commit`
-- If the summary body is unchanged, treat it as `summary skipped (no diff)`
-
-## Result Reporting
-
-Reuse the normalized result string from `.agents/rules/pr-sync.md` in this skill's user output or Activity Log.
+Failure records a warning but never blocks or rolls back the completed commit. `no-op` maps to `summary skipped (no diff)`.

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

@@ -1,21 +1,9 @@
 # Commit 阶段 PR 摘要同步
 
-> 详细聚合规则、隐藏标记、评论体模板、PATCH/POST 流程、Shell 安全约束和错误处理见 `.agents/rules/pr-sync.md`。执行本步骤前先读取该 rule。
+仅当 `{task-id}` 有效且 `task.md` 存在有效 `pr_number` 时执行；否则跳过。
 
-## 触发条件
+1. 调用 `agent-infra-internal platform-pr summary-context {task-id}` 获取 canonical 聚合输入。
+2. 按 `.agents/rules/pr-sync.md` 生成纯摘要正文并写入临时文件。
+3. 调用 `agent-infra-internal platform-pr summary-sync {task-id} --agent {agent} --body-file {summary-body-file}`。
 
-仅当以下条件同时满足时执行：
-- `{task-id}` 有效
-- `task.md` frontmatter 中存在有效 `pr_number`
-
-任一条件不满足时，跳过 PR 摘要同步并继续后续校验。
-
-## 执行要求
-
-- 按 `.agents/rules/pr-sync.md` 中的唯一权威模板生成或更新 `<!-- sync-pr:{task-id}:summary -->` 评论
-- 在本 skill 中，PR 摘要同步失败只记为警告，不阻塞已完成的 `git commit`
-- 如果摘要正文无变化，按 `summary skipped (no diff)` 处理
-
-## 结果回传
-
-将 `.agents/rules/pr-sync.md` 中的结果回传字符串用于当前 skill 的用户输出或 Activity Log 复用。
+同步失败只记录 warning，不阻塞或回滚已经完成的 commit。`no-op` 回传 `summary skipped (no diff)`。

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

@@ -18,13 +18,53 @@ For every task-related commit, append this Activity Log entry in `task.md`:
 - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit** by {agent} — {commit hash short} {commit subject}
 ```
 
-If the commit stage confirmed that the highest-round `review-code` artifact is Approved, `pre_head` equals its review baseline commit `R`, and the staged diff fingerprint `S` equals its reviewed diff fingerprint `F`, also write or refresh:
+If the commit stage confirmed that the highest-round `review-code` artifact is Approved, `pre_head == R`, complete worktree tree `W == T`, and normalized staged tree `S == T`, also write or refresh after a successful commit:
 
 ```yaml
 last_reviewed_commit: {new_head}
 ```
 
-This field is the preferred baseline for the `complete-task` `post-review-commit` gate. When any condition is not met, do not write or advance it.
+This field is the only baseline for the `complete-task` `post-review-commit` gate. When any condition is not met, do not write or advance it.
+
+### Scenario 5: Existing-PR push wrap-up
+
+After a new commit or the restricted push-only path is successfully pushed to an existing open PR, the only next step is to watch required checks for the new head:
+
+```text
+Next step - watch PR checks:
+  - Claude Code / OpenCode: /watch-pr {task-ref}
+  - Gemini CLI: /{{project}}:watch-pr {task-ref}
+  - Codex CLI: $watch-pr {task-ref}
+```
+
+If push fails, keep the task active and preserve local HEAD; show diagnostics and manual push guidance only, never `watch-pr` or `complete-task`. This scenario takes precedence over the final `prFlow` route below.
+
+### Scenario 4: pre-commit snapshot block
+
+This scenario ends the run before `git commit` and does not enter the successful post-commit scenario selection below. When any of `pre_head != R`, `W != T`, or `S != T` applies:
+
+- Do not run `git commit`, push, successful state updates, Issue/PR success sync, or the commit completion gate; preserve the current worktree and index.
+- Refresh task `updated_at`, `assigned_to`, and `agent_infra_version`, then append a done log with action `Commit`: `Blocked before git commit: reviewed snapshot mismatch (worktree added={a}, missing={m}, different={d}; staged added={a}, missing={m}, different={d})`.
+- User output must include `No commit was created.` and show Added/Missing/Different under both `Current worktree vs reviewed snapshot` and `Staged snapshot vs reviewed snapshot`; render an empty set as `- (none)` and list paths only in user output.
+- When `pre_head != R` or `W != T`, the only next step is a fresh `review-code`; when only `W == T && S != T`, tell the user to fix staging and rerun `commit` without re-review.
+
+Full re-review commands:
+
+```text
+Next step - re-run code review:
+  - Claude Code / OpenCode: /review-code {task-ref}
+  - Gemini CLI: /{{project}}:review-code {task-ref}
+  - Codex CLI: $review-code {task-ref}
+```
+
+Full staging-only retry commands:
+
+```text
+Next step - fix staging and retry commit:
+  - Claude Code / OpenCode: /commit {task-ref}
+  - Gemini CLI: /{{project}}:commit {task-ref}
+  - Codex CLI: $commit {task-ref}
+```
 
 Before selecting the next step, verify:
 - `current_step` and the latest workflow progress in `task.md`

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

@@ -18,13 +18,53 @@ date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
 - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit** by {agent} — {commit hash short} {commit subject}
 ```
 
-如果提交阶段已确认最高轮 `review-code` 产物 Approved、`pre_head` 等于其审查基线提交 `R`、且 staged 差异指纹 `S` 等于其审查差异指纹 `F`，同时写入或刷新：
+如果提交阶段已确认最高轮 `review-code` 产物 Approved、`pre_head == R`、完整工作区树 `W == T` 且规范化暂存树 `S == T`，成功提交后同时写入或刷新：
 
 ```yaml
 last_reviewed_commit: {new_head}
 ```
 
-该字段是 `complete-task` 的 `post-review-commit` gate 优先 baseline。条件不满足时不要写入或推进该字段。
+该字段是 `complete-task` 的 `post-review-commit` gate 唯一 baseline。条件不满足时不要写入或推进该字段。
+
+### 场景 5：已有 PR 推送收尾
+
+新 commit 或受限 push-only 场景成功推送到已有开放 PR 后，唯一下一步是监控新 head 的 required checks：
+
+```text
+下一步 - 监控 PR 检查：
+  - Claude Code / OpenCode: /watch-pr {task-ref}
+  - Gemini CLI: /{{project}}:watch-pr {task-ref}
+  - Codex CLI: $watch-pr {task-ref}
+```
+
+push 失败时保留任务 active 与本地 HEAD，只展示诊断和人工推送提示；不得渲染 `watch-pr` 或 `complete-task`。该场景优先于下方 `prFlow` 终态路由。
+
+### 场景 4：提交前快照阻断
+
+此场景在 `git commit` 前终止本轮，不进入下方提交成功后的场景选择。任一 `pre_head != R`、`W != T` 或 `S != T` 命中时：
+
+- 不执行 `git commit`、push、成功状态更新、Issue/PR 成功同步或 commit 完成 gate；保留当前工作区与暂存区。
+- 刷新任务的 `updated_at`、`assigned_to`、`agent_infra_version`，并以 action `Commit` 追加 done 日志：`Blocked before git commit: reviewed snapshot mismatch (worktree added={a}, missing={m}, different={d}; staged added={a}, missing={m}, different={d})`。
+- 用户输出必须包含 `No commit was created.`，并分别按 `Current worktree vs reviewed snapshot`、`Staged snapshot vs reviewed snapshot` 展示 Added/Missing/Different；空集合显示 `- (none)`，路径只在用户输出中逐行展示。
+- `pre_head != R` 或 `W != T` 时，下一步只指向重新 `review-code`；仅 `W == T && S != T` 时，提示修正暂存后重跑 `commit`，无需重审。
+
+重新审查的完整命令：
+
+```text
+下一步 - 重新代码审查：
+  - Claude Code / OpenCode: /review-code {task-ref}
+  - Gemini CLI: /{{project}}:review-code {task-ref}
+  - Codex CLI: $review-code {task-ref}
+```
+
+仅修正暂存的完整命令：
+
+```text
+下一步 - 修正暂存后重新提交：
+  - Claude Code / OpenCode: /commit {task-ref}
+  - Gemini CLI: /{{project}}:commit {task-ref}
+  - Codex CLI: $commit {task-ref}
+```
 
 在决定下一步之前，先确认：
 - `task.md` 中的 `current_step` 和最新工作流进度

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

@@ -3,6 +3,7 @@ name: complete-manual-validation
 description: >
   Mark PR manual validation as completed and update the manual-validation section
   in the existing PR summary comment in place.
+  Only invoke this skill automatically when the conversation includes a resolvable task reference.
 ---
 
 # Complete Manual Validation
@@ -23,24 +24,18 @@ After loading workflow / skill / rules instructions, and before any task-state j
 Run these commands and paste the raw output into both the user-facing reply and this round's `## State Check` section:
 
 ```bash
-git status -s
-ls -la .agents/workspace/active/{task-id}/
-tail .agents/workspace/active/{task-id}/task.md
+agent-infra-internal task-snapshot {task-id} --format text
 ```
 
-## Task id short ref
+## Task Context Resolution
 
-> If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
+> The entry point may omit the task ref and also accepts a legacy positional ref or `--task <ref>` / `-t <ref>`. Separate task scope from the full arguments while preserving every business operand, then call `agent-infra-internal task-context resolve {task-scope}` where `{task-scope}` is empty, one positional ref, or one task flag. Read only `taskId` from the structured result and bind `{task-id}` to that full `TASK-YYYYMMDD-HHMMSS` for downstream commands. Pass through resolution failures without scanning tasks locally.
 
-## Step Start: Write the started Marker
-
-After confirming prerequisites and the artifact round, and before this round's first artifact action, append a started marker to task.md `## Activity Log`:
+> Resolve the task reference, then confirm that the task is in a state or directory supported by this skill and that `task.md` exists; if it cannot be located, handle it as a missing task and stop.
 
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Manual Validation [started]** by {agent} — started
-```
+## Step Start: Write the started Marker
 
-See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+After resolving the artifact context and before this round's first artifact action, run `agent-infra-internal task-event {task-id} manual-validation.started --agent {agent}` and record the returned `artifactContext`.
 
 ## Steps
 
@@ -64,12 +59,9 @@ Check:
 
 Stop if the task is missing, the validation summary is missing, or no valid PR can be resolved.
 
-### 3. Determine Artifact Round
+### 3. Resolve the Artifact Context
 
-Scan the task directory:
-- no `manual-validation.md` and no `manual-validation-r*.md` -> write `manual-validation.md`
-- `manual-validation.md` exists and no `manual-validation-r*.md` -> write `manual-validation-r2.md`
-- `manual-validation-r{N}.md` exists -> write `manual-validation-r{N+1}.md`
+Run `agent-infra-internal task-artifact {task-id} inspect --family manual-validation`. Continue only for `ready`; take the round and `{manual-validation-artifact}` from `next.round` / `next.name`. Do not scan rounds or construct names in the skill. Then run the started event and verify the returned identity.
 
 ### 4. Update the PR Summary
 
@@ -78,7 +70,7 @@ Before this step, read:
 - `.agents/rules/pr-sync.md`
 - `reference/summary-update.md`
 
-Follow `reference/summary-update.md` to resolve the PR number, find the `sync-pr` summary comment, extract the manual-validation scope, and update the section to `### ✅ Manual Validation Passed`.
+Follow `reference/summary-update.md` to validate the PR binding, obtain canonical inputs from `platform-pr summary-context`, and update the manual-validation section through `platform-pr summary-sync` to `### ✅ Manual Validation Passed`.
 
 ### 5. Create the Manual Validation Artifact
 
@@ -91,31 +83,16 @@ Before this step, read `reference/report-template.md`. Create `{manual-validatio
 
 ### 6. Update task.md
 
-Get the current time:
-
-```bash
-date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\([+-][0-9][0-9]\)\([0-9][0-9]\)$/\1:\2/'
-```
-
-Update `.agents/workspace/active/{task-id}/task.md`:
-- `updated_at`: current time
-- `assigned_to`: current agent
-- `agent_infra_version`: value from `.agents/rules/version-stamp.md`
-- keep `current_step` unchanged
-- append the `{manual-validation-artifact}` link and PR summary sync result to `## Implementation Notes`
-- append Activity Log:
-  ```
-  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Manual Validation** by {agent} — Manual validation passed → {manual-validation-artifact}; {summary-result}
-  ```
+Run `agent-infra-internal task-event {task-id} manual-validation.completed --agent {agent} --artifact {manual-validation-artifact} --summary-result "{summary-result}"`. The core keeps `current_step` unchanged while atomically recording the implementation-notes link, metadata, and done log.
 
-If the task has a valid `issue_number`, follow `.agents/rules/issue-sync.md` to update the task comment and publish the `{manual-validation-artifact}` comment.
+If the task has a valid `issue_number`, run `agent-infra-internal platform-comment sync {task-id} --kind task --agent {agent}`, then `agent-infra-internal platform-comment sync {task-id} --kind artifact --artifact {manual-validation-artifact} --agent {agent}`.
 
 ### 7. Verification Gate
 
 Run:
 
 ```bash
-node .agents/scripts/validate-artifact.js gate complete-manual-validation .agents/workspace/active/{task-id} {manual-validation-artifact} --format text
+agent-infra-internal task-verify {task-id} manual-validation.completed --artifact {manual-validation-artifact} --format text
 ```
 
 Handle the result: