@fitlab-ai/agent-infra 0.7.5 → 0.7.7

package/templates/.agents/skills/check-task/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: check-task
-description: "查看任务的当前状态和进度"
+description: >
+  查看任务的当前状态和进度。
+  当想快速查看某个任务当前状态与进度时使用。
 ---
 
 # 查看任务状态
@@ -8,103 +10,51 @@ description: "查看任务的当前状态和进度"
 ## 行为边界 / 关键规则
 
 - 本技能是**只读**操作 —— 不修改任何文件
-- 始终检查 active、blocked 和 completed 目录
+- 机械数据（frontmatter 元数据、产物分组、Git/Platform 状态，以及跨 active、blocked、completed 三目录定位任务）一律委托给确定性的 `ai task status` 命令。本技能只负责 CLI 无法产出的语义层：工作流阶段解读、审查结论解析、下一步建议。
 
 ## 任务入参短号别名
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
 ## 执行步骤
-### 1. 查找任务
 
-按以下优先顺序搜索任务：
-1. `.agents/workspace/active/{task-id}/task.md`
-2. `.agents/workspace/blocked/{task-id}/task.md`
-3. `.agents/workspace/completed/{task-id}/task.md`
+### 1. 通过 `ai task status` 收集事实
 
-注意：`{task-id}` 格式为 `TASK-{yyyyMMdd-HHmmss}`，例如 `TASK-20260306-143022`
+运行确定性 CLI 收集全部机械数据，并以其 stdout 作为状态报告的事实基底：
 
-如果在任何目录中都未找到，提示 "Task {task-id} not found"。
-
-### 2. 读取任务元数据
+```bash
+ai task status {task-id}
+```
 
-从 `task.md` 中提取：
-- `id`、`title`、`type`、`status`、`workflow`
-- `current_step`、`assigned_to`
-- `created_at`、`updated_at`
-- `issue_number`、`pr_number`（如适用）
+该命令会跨 active、blocked、completed 三目录解析任务，并输出五段：任务头（`id`、短号、标题）、`Metadata`（frontmatter 字段）、`Artifacts`（按工作流阶段分组的产物）、`Git`（分支匹配、未提交数、ahead/behind）、`Platform`（Issue/PR 状态）。把该输出视为权威事实 —— 不要再手工复述其中任何内容。
 
-### 3. 检查上下文文件
+降级处理：
+- 若命令不可用（如 `ai` 不在 PATH 或 `dist/` 未构建）或非零退出，回退到降级读取：展示 `task.md` frontmatter 并 `ls` 任务目录，同时告知用户本次为降级输出（建议先构建或安装 CLI，如 `ai init`）。
+- 若在任何目录都未找到任务，提示 "Task {task-id} not found"。
 
-按产物类型扫描并记录以下文件的存在、轮次和状态：
-- `analysis.md`、`analysis-r{N}.md` - 需求分析
-- `plan.md`、`plan-r{N}.md` - 技术方案
-- `code.md`、`code-r2.md`、... - 实现报告
-- `review-analysis.md`、`review-analysis-r{N}.md` - 需求分析审查报告
-- `review-plan.md`、`review-plan-r{N}.md` - 技术方案审查报告
-- `review-code.md`、`review-code-r{N}.md` - 代码审查报告
+### 2. 解读工作流阶段与审查结论
 
-对于版本化产物（`analysis`、`review-analysis`、`plan`、`review-plan`、`code`、`review-code`）：
-- 扫描任务目录中的所有同类版本化文件
-- 记录每类产物的最新轮次、最新文件路径和总轮次数
-- 如果 `task.md` 的 Activity Log 记录了最新轮次，优先核对其与实际文件是否一致
+这是 CLI 不产出的语义层。基于步骤 1 的 `Artifacts` 分组与 `task.md` 的活动日志：
 
-### 4. 输出状态报告
+- 把每个工作流阶段映射为状态指示器，并标注其最新产物与轮次：
+  - `[done]` - 步骤已完成
+  - `[current]` - 当前进行中
+  - `[pending]` - 尚未开始
+  - `[blocked]` - 被阻塞
+  - `[skipped]` - 已跳过
+- 对各阶段最新的审查产物（`review-analysis`、`review-plan`、`review-code`），读取报告正文并解析结论：总体结论（通过 / 需要修改 / 拒绝）与阻塞项 / 主要问题 / 次要问题计数。CLI 不解析审查正文，因此这一步是步骤 3 选择下一步操作的必要输入。
 
-以清晰的结构和状态指示器格式化输出：
+把工作流进度作为 CLI 输出之上的叠加层呈现，标注最新轮次与解析出的审查结论，例如：
 
 ```
-任务状态：{task-id}（短号 {task-ref}）
-=======================
-
-基本信息：
-- 标题：{title}
-- 类型：{type}
-- 状态：{status}
-- 工作流：{workflow}
-- 分配给：{assigned_to}
-- 创建时间：{created_at}
-- 更新时间：{updated_at}
-
 工作流进度：
-  [已完成]    需求分析        analysis-r2.md (Round 2, latest)
-  [已完成]    需求分析审查    review-analysis.md (Round 1, latest)
-  [已完成]    技术设计        plan.md (Round 1)
-  [已完成]    技术方案审查    review-plan.md (Round 1, latest)
-  [进行中]    实现            code.md (Round 1)
-  [待处理]    代码审查        review-code.md (Round 1 will be created next)
-  [待处理]    最终提交
-
-上下文文件：
-- analysis.md：           已存在 (Round 1)
-- analysis-r2.md：        已存在 (Round 2, latest)
-- review-analysis.md：    已存在 (Round 1, latest)
-- plan.md：               已存在 (Round 1, latest)
-- review-plan.md：        已存在 (Round 1, latest)
-- code.md：               已存在 (Round 1, latest)
-- review-code.md：        未开始
-
-如果存在多轮产物，显示所有轮次，并标记最新版本，例如：
-- plan.md：             已存在 (Round 1)
-- plan-r2.md：          已存在 (Round 2, latest)
-- review-plan.md：      已存在 (Round 1)
-- code.md：             已存在 (Round 1)
-- code-r2.md：          已存在 (Round 2, latest)
-- review-code.md：      已存在 (Round 1)
-- review-code-r2.md：   已存在 (Round 2, latest)
-
-下一步：
-  完成实现，然后执行代码审查
+  [done]       需求分析        analysis.md (Round 1, latest)
+  [done]       需求分析审查    review-analysis.md (Round 1, latest, 通过)
+  [current]    技术设计        plan.md (Round 1)
+  [pending]    技术方案审查
 ```
 
-**状态指示器**：
-- `[done]` - 步骤已完成
-- `[current]` - 当前进行中
-- `[pending]` - 尚未开始
-- `[blocked]` - 被阻塞
-- `[skipped]` - 已跳过
-
-### 5. 建议下一步操作
+### 3. 建议下一步操作
 
 根据当前工作流状态，建议合适的下一个技能。必须展示下表中所有 TUI 列的命令格式，不要只展示当前 AI 代理对应的列。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）：
 
@@ -143,6 +93,6 @@ description: "查看任务的当前状态和进度"
 ## 注意事项
 
 1. **只读**：本技能仅读取和报告 —— 不修改任何文件
-2. **多目录搜索**：始终检查 active、blocked 和 completed 目录
+2. **CLI 委托**：机械数据（元数据、产物分组、Git/Platform 状态、多目录定位）来自 `ai task status`；本技能在其之上叠加语义解读
 3. **快速参考**：随时可以使用本技能检查任务在工作流中的位置
-4. **版本化产物**：`analysis`、`review-analysis`、`plan`、`review-plan`、`code`、`review-code` 都需要报告实际轮次，而不是只报告固定文件名
+4. **版本化产物**：`ai task status` 已按实际轮次分组产物；语义层仍需报告 `review-analysis`、`review-plan`、`review-code` 的最新审查结论

package/templates/.agents/skills/close-codescan/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: close-codescan
-description: "Close a Code Scanning alert with a documented reason"
+description: >
+  Close a Code Scanning alert with a documented reason.
+  Use when a Code Scanning alert has been handled or dismissed and needs closing with a reason.
 ---
 
 # Dismiss Code Scanning Alert
@@ -11,6 +13,16 @@ Dismiss the specified Code Scanning (CodeQL) alert and record a justified reason
 
 > 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.
 
+## Step Start: Write the started Marker
+
+After prerequisites pass and before this step's first artifact action, append a started marker to task.md `## Activity Log` (same base action as this step's done entry plus a ` [started]` suffix, note `started`):
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Close Codescan [started]** by {agent} — started
+```
+
+`ai task log` pairs it with the done entry written on completion onto one row (in progress → done). See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Execution Flow
 
 ### 1. Retrieve Alert Information

package/templates/.agents/skills/close-codescan/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: close-codescan
-description: "关闭 Code Scanning 告警并记录理由"
+description: >
+  关闭 Code Scanning 告警并记录理由。
+  当某条 Code Scanning 告警已处理或需按理由关闭时使用。
 ---
 
 # 关闭 Code Scanning 告警
@@ -11,6 +13,16 @@ description: "关闭 Code Scanning 告警并记录理由"
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：写入 started 标记
+
+确认前置条件后、本步骤第一个产出动作之前，向 task.md `## 活动日志` 追加一条 started 标记（与本步骤 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Close Codescan [started]** by {agent} — started
+```
+
+`ai task log` 会把它与完成时写入的 done 条目配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行流程
 
 ### 1. 获取告警信息

package/templates/.agents/skills/close-dependabot/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: close-dependabot
-description: "Close a Dependabot alert with a documented reason"
+description: >
+  Close a Dependabot alert with a documented reason.
+  Use when a Dependabot alert has been handled or dismissed and needs closing with a reason.
 ---
 
 # Dismiss Dependabot Alert
@@ -11,6 +13,16 @@ Dismiss the specified Dependabot security alert and record a justified reason.
 
 > 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.
 
+## Step Start: Write the started Marker
+
+After prerequisites pass and before this step's first artifact action, append a started marker to task.md `## Activity Log` (same base action as this step's done entry plus a ` [started]` suffix, note `started`):
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Close Dependabot [started]** by {agent} — started
+```
+
+`ai task log` pairs it with the done entry written on completion onto one row (in progress → done). See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Execution Flow
 
 ### 1. Retrieve Alert Information

package/templates/.agents/skills/close-dependabot/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: close-dependabot
-description: "关闭 Dependabot 安全告警并记录理由"
+description: >
+  关闭 Dependabot 安全告警并记录理由。
+  当某条 Dependabot 安全告警已处理或需按理由关闭时使用。
 ---
 
 # 关闭 Dependabot 告警
@@ -11,6 +13,16 @@ description: "关闭 Dependabot 安全告警并记录理由"
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：写入 started 标记
+
+确认前置条件后、本步骤第一个产出动作之前，向 task.md `## 活动日志` 追加一条 started 标记（与本步骤 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Close Dependabot [started]** by {agent} — started
+```
+
+`ai task log` 会把它与完成时写入的 done 条目配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行流程
 
 ### 1. 获取告警信息

package/templates/.agents/skills/code-task/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: code-task
-description: "Implement code from the technical plan and output a report"
+description: >
+  Implement code from the technical plan and output a report.
+  Use when an approved technical plan needs implementing, or code review found issues to fix.
 ---
 
 # Code Task
@@ -11,6 +13,7 @@ Implement the approved plan and produce `code.md` or `code-r{N}.md`. This skill
 
 - Follow the latest plan artifact: `plan.md` or `plan-r{N}.md`
 - Fix mode verifies each finding of the latest `review-code` one by one: fix it if it holds, or rebut it and record it under unresolved if it is unfounded/hallucinated; do not expand to issues the review did not list; env-blocked items are out of scope
+- If implementation encounters a key design decision not covered by the plan, record `[needs-human-decision]` / `HD-` rows according to `.agents/rules/no-mid-flow-questions.md` instead of asking mid-flow or expanding scope silently
 - Never auto-run `git add` or `git commit`
 - Create a new code artifact for each round and never overwrite an older one
 - After executing this skill, you **must** immediately update task.md
@@ -33,6 +36,16 @@ tail .agents/workspace/active/{task-id}/task.md
 
 > 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.
 
+## Step Start: Write the started Marker
+
+After prerequisites (step 1) and mode/round (step 4) are confirmed and before this round's first artifact action, append a started marker to task.md `## Activity Log` (same base action as this round's done entry plus a ` [started]` suffix, note `started`):
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Task (Round {N}) [started]** by {agent} — started
+```
+
+In fix mode the base must match this round's done entry, i.e. `Code Task (Round {N}, fix for {review-artifact}) [started]`. `ai task log` pairs it with the done entry written on completion (step 10) onto one row (in progress → done). Format and pairing rules: see the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Steps
 
 ### 1. Verify Prerequisites

package/templates/.agents/skills/code-task/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: code-task
-description: "根据技术方案编码任务并输出报告"
+description: >
+  根据技术方案编码任务并输出报告。
+  当技术方案已批准需要落地实现，或代码审查发现问题需要修复时使用。
 ---
 
 # 编码任务
@@ -11,6 +13,7 @@ description: "根据技术方案编码任务并输出报告"
 
 - 严格遵循最新方案产物：`plan.md` 或 `plan-r{N}.md`
 - 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；env-blocked 项不在修复范围
+- 实现中遇到方案未覆盖的关键设计决策时，按 `.agents/rules/no-mid-flow-questions.md` 判据记录 `[needs-human-decision]` / `HD-` 行，不中途提问或擅自扩范围
 - 绝不自动执行 `git add` 或 `git commit`
 - 每轮实现都创建新的实现产物，不覆盖旧文件
 - 执行本技能后，你**必须**立即更新 task.md
@@ -47,6 +50,16 @@ tail .agents/workspace/active/{task-id}/task.md
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：写入 started 标记
+
+确认前置条件（步骤 1）与模式/轮次（步骤 4）后、本轮第一个产出动作之前，向 task.md `## 活动日志` 追加一条 started 标记（与本轮 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Task (Round {N}) [started]** by {agent} — started
+```
+
+修复模式的基名须与本轮 done 一致，即 `Code Task (Round {N}, fix for {review-artifact}) [started]`。`ai task log` 会把它与步骤完成时（步骤 10）写入的 done 条目配对成一行（进行中 → 已完成）。格式与配对规则见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行步骤
 ### 1. 验证前置条件
 

package/templates/.agents/skills/code-task/reference/dual-mode.en.md

@@ -10,7 +10,7 @@ node .agents/skills/code-task/scripts/detect-mode.js .agents/workspace/active/{t
 
 The script scans `plan.md` / `plan-r{N}.md`, `review-plan.md` / `review-plan-r{N}.md`, `code.md` / `code-r{N}.md`, and `review-code.md` / `review-code-r{N}.md` in the task directory.
 
-## Eight Branches
+## Seven Branches
 
 > Branches are evaluated top-down in this table; the first match returns and skips later rows.
 
@@ -19,12 +19,17 @@ The script scans `plan.md` / `plan-r{N}.md`, `review-plan.md` / `review-plan-r{N
 | no code artifact | `init` | 0 | initial implementation, output `code.md` |
 | latest review-plan is approved (`Approved` or `Approved-with-issues`, i.e. `Overall Verdict: Approved` regardless of findings counts), its "Review Input" / "审查输入" entry names the same plan file as the latest `plan(-r{N})?.md` in the task directory, and its mtime is newer than the latest code artifact | `init` | 0 | plan has been approved after the latest code; enter a new implementation round, `next_round = code_max + 1`, `next_artifact = code-r{next_round}.md`. This branch fires regardless of whether review-code exists or passes. Plan and review-plan rounds are independent counters (e.g. `plan-r5` may be approved by `review-plan-r4`); the link is established via the review-plan's "Review Input" entry, not by matching round numbers. |
 | `rev_max < code_max` | `error` | 2 | latest code round is unreviewed; run `review-code` first |
-| `rev_max > code_max` | `error` | 2 | inconsistent state; manual inspection required |
 | latest review-code is Approved with 0/0/0 | `refused` | 1 | already approved; do not run `code-task` again |
 | latest review-code is Approved with major/minor findings | `fix` | 0 | optional fix mode |
 | latest review-code is Changes Requested | `fix` | 0 | required fix mode |
 | latest review-code is Rejected | `refused` | 1 | re-plan instead of local fixing |
 
+> The four verdict branches above fire when `rev_max >= code_max`, decided by the latest `review-code-r{rev_max}` verdict:
+> - `rev_max == code_max`: AI fix round (`review-code` reviews the same-numbered code artifact produced by `code-task`).
+> - `rev_max > code_max`: human-supplemented review round — after a PR is opened a maintainer appends a `review-code-r{N}` round against the existing latest code. `fix` mode then uses `next_round = code_max + 1`.
+>
+> If the latest `review-code` verdict cannot be parsed, the script still returns `error` (exit 2) as the retained anomaly guard.
+
 ## Verdict Parsing
 
 The script supports zh-CN and English review-code reports:

package/templates/.agents/skills/code-task/reference/dual-mode.zh-CN.md

@@ -10,7 +10,7 @@ node .agents/skills/code-task/scripts/detect-mode.js .agents/workspace/active/{t
 
 脚本扫描任务目录中的 `plan.md` / `plan-r{N}.md`、`review-plan.md` / `review-plan-r{N}.md`、`code.md` / `code-r{N}.md` 和 `review-code.md` / `review-code-r{N}.md`。
 
-## 8 个分支
+## 7 个分支
 
 > 分支按表中自上而下的顺序评估，命中即返回；后续分支不再判定。
 
@@ -19,12 +19,17 @@ node .agents/skills/code-task/scripts/detect-mode.js .agents/workspace/active/{t
 | 无 code 产物 | `init` | 0 | 初次实现，产物为 `code.md` |
 | 最新 review-plan 已批准（`通过` 或 `通过 + major/minor 建议`，即 `Approved` 或 `Approved-with-issues`），且其「审查输入」/「Review Input」字段引用的 plan 文件 == 任务目录中最新的 `plan(-r{N})?.md`，且最新 review-plan 的 mtime > 最新 code 的 mtime | `init` | 0 | plan 已在 code 之后被批准；进入新一轮实现，`next_round = code_max + 1`、`next_artifact = code-r{next_round}.md`。**不论 review-code 是否已审**，本分支均先命中。plan 与 review-plan 的轮次独立递增（如 `plan-r5` 可被 `review-plan-r4` 批准），通过 review-plan 的「审查输入」字段建立批准关系，不要求同号 |
 | `rev_max < code_max` | `error` | 2 | 最新代码未审查，先运行 `review-code` |
-| `rev_max > code_max` | `error` | 2 | 数据状态异常，需要人工检查 |
 | 最新 review-code 为 Approved 且 0/0/0 | `refused` | 1 | 已通过，无需再次运行 `code-task` |
 | 最新 review-code 为 Approved 但有 major/minor | `fix` | 0 | 可选修复模式 |
 | 最新 review-code 为 Changes Requested | `fix` | 0 | 必需修复模式 |
 | 最新 review-code 为 Rejected | `refused` | 1 | 需要重新设计，不进入局部修复 |
 
+> 上表 4 个 verdict 分支在 `rev_max >= code_max` 时命中，均以最新 `review-code-r{rev_max}` 的结论决定：
+> - `rev_max == code_max`：AI 修复轮（`code-task` 产出代码后由 `review-code` 审查同号产物）。
+> - `rev_max > code_max`：人工补审轮——PR 创建后维护者追加一轮 `review-code-r{N}` 审查既有最新代码。此时 `fix` 模式的 `next_round = code_max + 1`。
+>
+> 若最新 `review-code` 的 verdict 无法解析，仍返回 `error`（exit 2），作为保留的异常拦截。
+
 ## verdict 解析
 
 脚本支持中文和英文 review-code 报告：

package/templates/.agents/skills/code-task/scripts/detect-mode.js

@@ -84,20 +84,12 @@ function main() {
       return;
     }
 
-    if (revMax > codeMax) {
-      writeResult({
-        mode: "error",
-        code_max: codeMax,
-        rev_max: revMax,
-        verdict: null,
-        next_round: null,
-        next_artifact: null,
-        review_artifact: artifactName("review-code", revMax),
-        message: `Inconsistent state: review-code round ${revMax} > code round ${codeMax}. Manual inspection required.`
-      }, 2);
-      return;
-    }
-
+    // human-supplemented review: after a PR is opened, a maintainer may append a
+    // review-code-r{N} round against the existing latest code, so rev_max > code_max.
+    // This is NOT corruption — defer to the latest review's verdict instead of erroring.
+    // rev_max === code_max (AI fix round) and rev_max > code_max (human review round)
+    // both fall through to the verdict dispatch below; fix mode uses next_round = code_max + 1.
+    // An unparsable verdict still returns error (exit 2) as the retained anomaly guard.
     const reviewArtifact = artifactName("review-code", revMax);
     const verdictResult = parseVerdict(path.join(resolvedTaskDir, reviewArtifact));
     if (!verdictResult.ok) {

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

@@ -1,6 +1,8 @@
 ---
 name: commit
-description: "Commit the current changes to Git"
+description: >
+  Commit the current changes to Git.
+  Use when finished work needs to be turned into a Git commit.
 ---
 
 # Commit Changes
@@ -21,6 +23,16 @@ When updating related `task.md` frontmatter, read `.agents/rules/version-stamp.m
 
 > 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.
 
+## Step Start: Write the started Marker
+
+Before checking local modifications, append a started marker to task.md `## Activity Log` (same base action as this step's done entry plus a ` [started]` suffix, note `started`):
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit [started]** by {agent} — started
+```
+
+`ai task log` pairs it with the done entry written when the commit completes onto one row (in progress → done). Format and pairing rules: see the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`. Only write it when this task has a task.md (a bare commit with no task context may skip it).
+
 ## 1. Check Local Modifications (CRITICAL)
 
 Before any edit, inspect:
@@ -54,7 +66,27 @@ If this commit is associated with a task and a `review-code` artifact exists, re
 - 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
 - Do not scan backward to earlier Approved artifacts; the highest-round `review-code` artifact is the only authoritative source
 
-## 5. Update Task Status When Applicable
+## 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.
+
+> 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.
+
+a. Detect whether the current branch (head) has an open PR per `.agents/rules/issue-pr-commands.md`.
+
+b. On an open PR -> push the current branch:
+
+```bash
+git 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.
+   - `git push` fails (needs `git pull --rebase`, no upstream, network error) -> keep the local commit and tell the user to push manually.
+
+Fold the push outcome (pushed / skipped(no PR) / failed) into the next step's "Update Task Status" Activity Log note or user output.
+
+## 6. Update Task Status When Applicable
 
 Get the current time:
 
@@ -71,7 +103,7 @@ Append the Commit Activity Log entry and choose exactly one next-step case:
 - more work remains -> update task.md and stop
 - ready for review -> `review-code {task-id}`
 
-## 6. Sync Issue Metadata When Applicable
+## 7. Sync Issue Metadata When Applicable
 
 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.
 
@@ -81,7 +113,7 @@ When `{task-id}` exists and task.md contains a valid `issue_number`, sync the li
 
 Failure handling matches "Update Task Status When Applicable": warn, but do **not** block an already completed `git commit`.
 
-## 7. Sync PR Summary When Applicable
+## 8. Sync PR Summary When Applicable
 
 When `{task-id}` exists and task.md contains a valid `pr_number`, refresh the PR summary comment marked with the PR summary marker defined in `.agents/rules/pr-sync.md` on the PR. Otherwise, skip this step.
 
@@ -91,7 +123,7 @@ When `{task-id}` exists and task.md contains a valid `pr_number`, refresh the PR
 
 Failure handling matches "Update Task Status When Applicable": warn, but do **not** block an already completed `git commit`.
 
-## 8. Verification Gate
+## 9. Verification Gate
 
 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.
 

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

@@ -1,6 +1,8 @@
 ---
 name: commit
-description: "提交当前变更到 Git"
+description: >
+  提交当前变更到 Git。
+  当需要把已完成的工作落为一次 Git 提交时使用。
 ---
 
 # 提交代码
@@ -21,6 +23,16 @@ description: "提交当前变更到 Git"
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：写入 started 标记
+
+开始检查本地修改之前，向 task.md `## 活动日志` 追加一条 started 标记（与本步骤 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit [started]** by {agent} — started
+```
+
+`ai task log` 会把它与提交完成时写入的 done 条目配对成一行（进行中 → 已完成）。格式与配对规则见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。仅当本任务存在 task.md 时写入（无任务上下文的纯提交可跳过）。
+
 ## 1. 检查本地修改（关键）
 
 在任何编辑前先检查：
@@ -54,7 +66,27 @@ git diff
 - 提交后仅当 `pre_head == R` 且 `S == F` 时，在 task.md frontmatter 写入 `last_reviewed_commit: <new_head>`；否则不推进该字段
 - 不向后扫描更早的 Approved 产物；最高轮 `review-code` 产物是唯一权威来源
 
-## 5. 按需更新任务状态
+## 5. 推送到已有 PR（按需）
+
+提交完成后，如果当前分支已存在开放的 Pull Request，则把本次提交推送上去让 PR 自动更新；否则保持现状（首次推送仍由 `create-pr` 负责）。本步骤是用户已发起 `commit` 的推送收尾，不新增自动提交，也不在无 PR 时推送；与是否关联任务无关。
+
+> 检测当前分支是否有开放 PR、以及平台认证，统一按 `.agents/rules/issue-pr-commands.md` 执行；该规则不可用或检测失败时，按下方降级处理。
+
+a. 按 `.agents/rules/issue-pr-commands.md` 检测当前分支（head）是否存在开放 PR。
+
+b. 命中开放 PR -> 推送当前分支：
+
+```bash
+git push
+```
+
+c. 安全降级（不阻塞已完成的 `git commit`，仅提示用户）：
+   - 平台不可用 / 未认证 / 检测失败 / 未命中开放 PR -> 不推送，继续后续步骤。
+   - `git push` 失败（如需 `git pull --rebase`、无 upstream、网络异常）-> 保留本地提交，提示用户手动推送。
+
+把推送结果（pushed / skipped(no PR) / failed）并入下一步「更新任务状态」的 Activity Log 说明或用户输出。
+
+## 6. 按需更新任务状态
 
 获取当前时间：
 
@@ -71,7 +103,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 还有后续工作 -> 更新 task.md 后停止
 - 准备审查 -> `review-code {task-id}`
 
-## 6. 同步 Issue 元数据（按需）
+## 7. 同步 Issue 元数据（按需）
 
 当 `{task-id}` 存在且 task.md 包含有效 `issue_number` 时，同步 `in:` label 和需求复选框到关联 Issue；否则跳过。
 
@@ -81,7 +113,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 
 失败处理与「按需更新任务状态」一致：警告但**不**阻塞已完成的 `git commit`。
 
-## 7. 同步 PR 摘要（按需）
+## 8. 同步 PR 摘要（按需）
 
 当 `{task-id}` 存在且 task.md 包含有效 `pr_number` 时，刷新 PR 上由 `.agents/rules/pr-sync.md` 中定义的 PR 摘要评论标记对应的摘要评论；否则跳过。
 
@@ -91,7 +123,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 
 失败处理与「按需更新任务状态」一致：警告但**不**阻塞已完成的 `git commit`。
 
-## 8. 完成校验
+## 9. 完成校验
 
 如果本次操作关联了 `{task-id}`，运行完成校验，确认任务元数据和同步状态符合规范；如果没有任务上下文，跳过本步骤。
 

package/templates/.agents/skills/complete-task/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: complete-task
-description: "Mark a task as completed and archive it"
+description: >
+  Mark a task as completed and archive it.
+  Use when a task's work is done and verified and you want to close and archive it.
 ---
 
 # Complete Task
@@ -30,6 +32,16 @@ Before the state check is complete, do not make external-state assertions such a
 
 > 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.
 
+## Step Start: Write the started Marker
+
+After confirming the task exists and before this round's first artifact action, append a started marker to task.md `## Activity Log` (same base action as this round's done entry plus a ` [started]` suffix, note `started`):
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Task [started]** by {agent} — started
+```
+
+`ai task log` pairs it with the done entry written on completion onto one row (in progress → done). Format and pairing rules: see the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Steps
 
 ### 1. Verify Task Exists

package/templates/.agents/skills/complete-task/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: complete-task
-description: "标记任务完成并归档"
+description: >
+  标记任务完成并归档。
+  当任务工作已完成并验证、需要收尾归档时使用。
 ---
 
 # 完成任务
@@ -30,6 +32,16 @@ tail .agents/workspace/active/{task-id}/task.md
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：写入 started 标记
+
+确认任务存在后、本轮第一个产出动作之前，向 task.md `## 活动日志` 追加一条 started 标记（与本轮 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Complete Task [started]** by {agent} — started
+```
+
+`ai task log` 会把它与完成时写入的 done 条目配对成一行（进行中 → 已完成）。格式与配对规则见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行步骤
 ### 1. 验证任务存在