@fitlab-ai/agent-infra 0.7.6 → 0.8.0

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

@@ -1,6 +1,8 @@
 ---
 name: cancel-task
-description: "Cancel an unneeded task and move it"
+description: >
+  Cancel an unneeded task and move it.
+  Use when a task is no longer needed and should be dropped from active work.
 ---
 
 # Cancel Task

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

@@ -1,6 +1,8 @@
 ---
 name: cancel-task
-description: "取消不再需要的任务并转移"
+description: >
+  取消不再需要的任务并转移。
+  当某个任务不再需要、应从 active 工作中撤下时使用。
 ---
 
 # 取消任务

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

@@ -1,6 +1,8 @@
 ---
 name: check-task
-description: "Check a task's current status and progress"
+description: >
+  Check a task's current status and progress.
+  Use when you want a quick view of a task's current status and progress.
 ---
 
 # Check Task Status
@@ -8,7 +10,7 @@ description: "Check a task's current status and progress"
 ## Boundary / Critical Rules
 
 - This skill is **read-only** -- do not modify any files
-- Always check the active, blocked, and completed directories
+- Mechanical facts (frontmatter metadata, artifact grouping, git/platform state, and locating the task across the active, blocked, and completed directories) are delegated to the deterministic `ai task status` command. This skill only adds the semantic layer the CLI cannot produce: workflow-stage interpretation, review-verdict parsing, and the next-step recommendation.
 
 ## Task id short ref
 
@@ -16,96 +18,43 @@ description: "Check a task's current status and progress"
 
 ## Steps
 
-### 1. Locate Task
+### 1. Gather Facts via `ai task status`
 
-Search for the task in this priority order:
-1. `.agents/workspace/active/{task-id}/task.md`
-2. `.agents/workspace/blocked/{task-id}/task.md`
-3. `.agents/workspace/completed/{task-id}/task.md`
+Run the deterministic CLI to collect every mechanical fact, and use its stdout as the factual base of your report:
 
-Note: `{task-id}` format is `TASK-{yyyyMMdd-HHmmss}`, for example `TASK-20260306-143022`
-
-If the task is not found in any directory, prompt "Task {task-id} not found".
-
-### 2. Read Task Metadata
+```bash
+ai task status {task-id}
+```
 
-Extract from `task.md`:
-- `id`, `title`, `type`, `status`, `workflow`
-- `current_step`, `assigned_to`
-- `created_at`, `updated_at`
-- `issue_number`, `pr_number` (if applicable)
+The command resolves the task across the active, blocked, and completed directories and prints five sections: the task header (`id`, short id, title), `Metadata` (frontmatter fields), `Artifacts` (files grouped by workflow stage), `Git` (branch match, uncommitted count, ahead/behind), and `Platform` (Issue/PR state). Treat that output as authoritative -- do not re-derive any of it by hand.
 
-### 3. Inspect Context Files
+Fallbacks:
+- If the command is unavailable (e.g. `ai` is not on PATH or `dist/` is not built) or exits non-zero, fall back to a degraded read: show the `task.md` frontmatter and `ls` the task directory, and tell the user the output is degraded (suggest building or installing the CLI, e.g. `ai init`).
+- If the task is not found in any directory, prompt "Task {task-id} not found".
 
-Scan and record the existence, round, and status of these artifact types:
-- `analysis.md`, `analysis-r{N}.md` - Requirement analysis
-- `plan.md`, `plan-r{N}.md` - Technical plan
-- `code.md`, `code-r2.md`, ... - Code reports
-- `review-analysis.md`, `review-analysis-r{N}.md` - Requirement analysis review reports
-- `review-plan.md`, `review-plan-r{N}.md` - Technical plan review reports
-- `review-code.md`, `review-code-r{N}.md` - Code review reports
+### 2. Interpret Workflow Stage & Review Verdicts
 
-For versioned artifacts (`analysis`, `review-analysis`, `plan`, `review-plan`, `code`, `review-code`):
-- Scan all versioned files of the same artifact type in the task directory
-- Record the latest round, latest file path, and total number of rounds for each artifact type
-- If the latest round is recorded in `task.md` Activity Log, cross-check it against the actual file when possible
+This is the semantic layer the CLI does not produce. Using the `Artifacts` groups from step 1 and the Activity Log in `task.md`:
 
-### 4. Output Status Report
+- Map each workflow stage to a status indicator plus its latest artifact and round:
+  - `[done]` - step completed
+  - `[current]` - currently in progress
+  - `[pending]` - not started yet
+  - `[blocked]` - blocked
+  - `[skipped]` - skipped
+- For the latest review artifact of each stage (`review-analysis`, `review-plan`, `review-code`), read the report body and parse its conclusion: the overall verdict (Approved / Changes Requested / Rejected) and the blocker / major / minor counts. The CLI does not parse review bodies, so this reading is required to choose the next action in step 3.
 
-Format the status report with a clear structure and status indicators:
+Present the workflow progress as an overlay on top of the CLI output, marking the latest round and the parsed review verdict, for example:
 
 ```
-Task status: {task-id} (short id {task-ref})
-=======================
-
-Basic info:
-- Title: {title}
-- Type: {type}
-- Status: {status}
-- Workflow: {workflow}
-- Assigned to: {assigned_to}
-- Created at: {created_at}
-- Updated at: {updated_at}
-
 Workflow progress:
-  [done]       Requirement Analysis  analysis-r2.md (Round 2, latest)
-  [done]       Analysis Review       review-analysis.md (Round 1, latest)
-  [done]       Technical Design      plan.md (Round 1)
-  [done]       Plan Review           review-plan.md (Round 1, latest)
-  [current]    Code                  code.md (Round 1)
-  [pending]    Code Review           review-code.md (Round 1 will be created next)
-  [pending]    Final Commit
-
-Context files:
-- analysis.md:           Exists (Round 1)
-- analysis-r2.md:        Exists (Round 2, latest)
-- review-analysis.md:    Exists (Round 1, latest)
-- plan.md:               Exists (Round 1, latest)
-- review-plan.md:        Exists (Round 1, latest)
-- code.md:               Exists (Round 1, latest)
-- review-code.md:        Not started
-
-If multiple rounds exist, show all rounds and mark the latest, for example:
-- plan.md:             Exists (Round 1)
-- plan-r2.md:          Exists (Round 2, latest)
-- review-plan.md:      Exists (Round 1)
-- code.md:             Exists (Round 1)
-- code-r2.md:          Exists (Round 2, latest)
-- review-code.md:      Exists (Round 1)
-- review-code-r2.md:   Exists (Round 2, latest)
-
-Next step:
-  Complete implementation, then run code review
+  [done]       Requirement Analysis  analysis.md (Round 1, latest)
+  [done]       Analysis Review       review-analysis.md (Round 1, latest, Approved)
+  [current]    Technical Design      plan.md (Round 1)
+  [pending]    Plan Review
 ```
 
-**Status indicators**:
-- `[done]` - Step completed
-- `[current]` - Currently in progress
-- `[pending]` - Not started yet
-- `[blocked]` - Blocked
-- `[skipped]` - Skipped
-
-### 5. Recommend Next Action
+### 3. Recommend Next Action
 
 Recommend the appropriate next skill based on the current workflow state. You must show command formats for all TUI columns in the table below, not just the current AI agent. 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).
 
@@ -144,6 +93,6 @@ Recommend the appropriate next skill based on the current workflow state. You mu
 ## Notes
 
 1. **Read-only**: This skill only reads and reports -- it does not modify files
-2. **Multi-directory search**: Always check active, blocked, and completed
+2. **CLI delegation**: mechanical facts (metadata, artifact grouping, git/platform state, multi-directory location) come from `ai task status`; this skill adds the semantic interpretation on top
 3. **Quick reference**: Use this skill any time you need to see where a task is in the workflow
-4. **Versioned artifacts**: `analysis`, `review-analysis`, `plan`, `review-plan`, `code`, and `review-code` must all report the actual round, not only the base filename
+4. **Versioned artifacts**: `ai task status` groups the actual artifact rounds; the semantic layer must still report the latest review verdict for `review-analysis`, `review-plan`, and `review-code`

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

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 告警

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

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

@@ -1,6 +1,8 @@
 ---
 name: close-dependabot
-description: "关闭 Dependabot 安全告警并记录理由"
+description: >
+  关闭 Dependabot 安全告警并记录理由。
+  当某条 Dependabot 安全告警已处理或需按理由关闭时使用。
 ---
 
 # 关闭 Dependabot 告警

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,7 +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
+- If implementation encounters a key design decision not covered by the plan, per `.agents/rules/no-mid-flow-questions.md` write its detail block into the implementation report's `## 人工裁决待办` (Pending Human Decisions) section as `### HD-N：<title> [needs-human-decision]` (`HD-N` is globally unique, see `.agents/rules/review-handshake.md`) and write the matching `HD-` ledger row, 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

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

@@ -1,6 +1,8 @@
 ---
 name: code-task
-description: "根据技术方案编码任务并输出报告"
+description: >
+  根据技术方案编码任务并输出报告。
+  当技术方案已批准需要落地实现，或代码审查发现问题需要修复时使用。
 ---
 
 # 编码任务
@@ -11,7 +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-` 行，不中途提问或擅自扩范围
+- 实现中遇到方案未覆盖的关键设计决策时，按 `.agents/rules/no-mid-flow-questions.md` 判据，把详情块写入实现报告的 `## 人工裁决待办` 段 `### HD-N：<标题> [needs-human-decision]`（`HD-N` 全局唯一，见 `.agents/rules/review-handshake.md`）并回写 `HD-` 账本行，不中途提问或擅自扩范围
 - 绝不自动执行 `git add` 或 `git commit`
 - 每轮实现都创建新的实现产物，不覆盖旧文件
 - 执行本技能后，你**必须**立即更新 task.md

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
@@ -64,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:
 
@@ -81,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.
 
@@ -91,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.
 
@@ -101,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 提交时使用。
 ---
 
 # 提交代码
@@ -64,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. 按需更新任务状态
 
 获取当前时间：
 
@@ -81,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；否则跳过。
 
@@ -91,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 摘要评论标记对应的摘要评论；否则跳过。
 
@@ -101,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
@@ -128,6 +130,7 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - `status`: completed
 - `current_step`: completed
 - `completed_at`: {current timestamp}
+- `target_date`: write the date portion (`YYYY-MM-DD`) of `completed_at` only when empty; keep any existing (human-entered) value
 - `updated_at`: {current timestamp}
 - `agent_infra_version`: value from `.agents/rules/version-stamp.md`
 - Add or update the `## State Check` section with the raw Step 0 audit command output, including `$ ` prompt lines, before `## Activity Log`