@fitlab-ai/agent-infra 0.7.5 → 0.7.7

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -1,9 +1,10 @@
 # 下一步输出规则
 
-本文件定义 skill「告知用户 / 下一步」输出的两类**相互独立**的规则；渲染最终输出前先读取本文件并同时落实两者：
+本文件定义 skill「告知用户 / 下一步」输出的三类**相互独立**的规则（第 3 类仅 review-* 适用）；渲染最终输出前先读取本文件并落实其中适用的规则：
 
 1. **下一步输出结构**：「下一步」命令与「任务信息」段如何呈现任务 ID 形态（占位符 / 取短号 / 回退）。
 2. **Agent 输出收尾行（Completed at）**：面向用户输出的**绝对最后一行**，**独立于「下一步」块**，正常 / 错误 / 早退路径都适用。
+3. **人工裁决待办前置块**：仅 `review-analysis` / `review-plan` / `review-code`，且本阶段存在待裁决项（`{h} > 0`）时适用——在「下一步」命令前展开待裁决项并提示先完成裁决。
 
 ## 占位符语义
 
@@ -60,3 +61,27 @@ Completed at: YYYY-MM-DD HH:mm:ss
 - 取值命令（本地时区、不带偏移）：`date "+%Y-%m-%d %H:%M:%S"`
 - 位置：必须是整段面向用户输出的最后一行，排在所有「下一步」命令之后。若某场景在命令之后还有条件性提醒行（如 env-blocked 提醒），收尾行排在该提醒行之后。
 - 该行只用于终端扫视，不写入任何产物文件或 Issue/PR 评论；完成时刻的单一事实源仍是 task.md 的 Activity Log。
+
+## 人工裁决待办前置块（review-* 专用，{h} > 0 时）
+
+本节是与上面两类规则**并列的第三类独立规则**，仅 `review-analysis` / `review-plan` / `review-code` 的「向用户汇报结论」步骤使用。
+
+`{h}` 含义与各 review 技能 `reference/output-templates.md` 计数行一致：task.md `## 审查分歧账本` 中**本阶段**（`stage ∈ {analysis|plan|code}`）`status = needs-human-decision` 的行数——**只含待裁决项，不含已 `human-decided`**。
+
+- **`{h} = 0`**：不输出本块，「下一步」按 output-templates 选定场景原样渲染。
+- **`{h} > 0`**：在选定场景的「下一步 - <阶段>」命令**之前**插入下面的块；下一阶段命令仍照常列在块之后。
+
+```text
+⚠️ 待人工裁决（{h} 项）—— 请先逐项裁决，再继续下一阶段：
+  - {ledger-id}（{stage}/{severity}）：{摘要}
+    位置：task.md `## 审查分歧账本` 对应行 · 证据：{evidence}
+  …（task.md `## 审查分歧账本` 中本阶段每个 status=needs-human-decision 行一条）
+
+完成裁决：
+  1. 在 task.md `## 人工裁决` 段，逐项记录你对上述裁决项的裁定与理由。
+  2. 把 `## 审查分歧账本` 中对应行的 status 由 `needs-human-decision` 翻为 `human-decided`。
+
+说明：在上述行全部翻为 `human-decided` 之前，直接执行下一阶段命令会被 complete-task 等 gate 拦截（`needs-human-decision` 为非终态）。下一阶段命令仍列在下方，供裁决完成后使用。
+```
+
+字段取值：`{ledger-id}` / `{stage}` / `{severity}` / `{evidence}` 直接取自 `## 审查分歧账本` 对应行的同名列；`{摘要}` 取自 `{evidence}` 指向的产物锚点条目（如 `plan.md#HD-1` 的决策标题），无锚点标题时用该 finding 的一句话概述。

package/templates/.agents/rules/no-mid-flow-questions.en.md

@@ -53,6 +53,17 @@ For every SKILL execution context not covered by any exemption above, the defaul
    - Meaning: the assumptions section records assumptions used for this run that may be revisited later; the open questions section records unresolved questions for human review
    - If the artifact template does not reserve these sections, append them as needed. If there are no assumptions or open questions, do not force empty sections.
 
+## Key Design Decision Marking And Ledgering
+
+When an open question is a key design decision that needs human judgment, the executor must mark the item with `[needs-human-decision]` and write the matching `HD-` row to task.md `## Review Disagreement Ledger` according to `.agents/rules/review-handshake.md`.
+
+Use these checks together:
+
+- **Source test**: can the conclusion be uniquely derived from the task description, existing requirements, code conventions, or an approved plan? If not, and multiple reasonable options exist, it is a choice.
+- **Impact test**: does the choice change scope, boundaries, defaults, thresholds, become irreversible / costly, or set precedent for later tasks? Any hit upgrades it to a key design decision.
+- **Small-impact exemption**: if it is only a local, reversible, low-cost execution detail, record it under `## Assumptions` instead of upgrading it to a human ruling.
+- **Fallback**: when unsure whether it is key, treat it as key; `review-*` must check whether the executor missed any `[needs-human-decision]` markings that should have been upgraded.
+
 ## Human Review Checkpoint Semantics
 
 A mandatory human review checkpoint means:

package/templates/.agents/rules/no-mid-flow-questions.zh-CN.md

@@ -53,6 +53,17 @@
    - 含义：`假设` 段记录本次按某假设推进、未来若假设不成立可推翻；`未决问题` 段记录本次未决、需要人工审查时裁定的问题
    - 产物模板未预留这两段时，按需追加；没有假设或未决问题时不必强行写空段。
 
+## 关键设计决策标记与落账
+
+当未决问题属于需要人工裁定的关键设计决策时，执行方必须在该条目前标记 `[needs-human-decision]`，并按 `.agents/rules/review-handshake.md` 在 task.md `## 审查分歧账本` 写入 `HD-` 行。
+
+判定时同时使用以下检查：
+
+- **来源测试**：结论是否能从任务描述、既有需求、代码约定或已批准方案中唯一推出？若不能，且存在多个合理选项，则它是选择题。
+- **影响测试**：该选择是否改变范围、边界、默认值、阈值，是否不可逆 / 成本较高，或是否会扩散成后续任务先例？任一命中即升级为关键设计决策。
+- **小影响豁免**：若它只是局部、可逆、低成本的执行细节，写入 `## 假设` 即可，不升级为人工裁决。
+- **兜底**：无法判断是否关键时按关键处理；`review-*` 需要复核执行方是否漏标应升级的 `[needs-human-decision]`。
+
 ## 人工审查检查点语义
 
 「强制性人工审查检查点」（mandatory human review checkpoint）的语义是：

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

@@ -58,13 +58,27 @@ The single source of truth for disagreement state is the fixed `## 审查分歧
 | CD-1 | code | 1 | blocker | open | review-code.md#1 |
 ```
 
-- `id`: stage prefix + ordinal — analysis→`AN-`, plan→`PL-`, code→`CD-`.
+- `id`: stage prefix + ordinal — analysis→`AN-`, plan→`PL-`, code→`CD-`; executor-raised human-ruling rows use `HD-`.
 - `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`.
 - **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 marks an item in the artifact `## Open Questions` section as `[needs-human-decision]`, it must upsert the matching `HD-` row in task.md `## Review Disagreement Ledger`:
+
+```markdown
+| HD-1 | plan | - | decision | needs-human-decision | plan.md#HD-1 |
+```
+
+- `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.
+- 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.
+
 ## post-review commit gate (code stage only)
 
 - The highest-round `review-code` report records `Review Baseline Commit` (R, `git rev-parse HEAD`) and `Reviewed Diff Fingerprint` (F, full worktree diff fingerprint).

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

@@ -58,13 +58,27 @@
 | CD-1 | code | 1 | blocker | open | review-code.md#1 |
 ```
 
-- `id`：阶段前缀 + 序号——analysis→`AN-`、plan→`PL-`、code→`CD-`。
+- `id`：阶段前缀 + 序号——analysis→`AN-`、plan→`PL-`、code→`CD-`；执行方自提的人工裁决行使用 `HD-`。
 - `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`。
 - **向后兼容**：task.md 无此段时，gate 视为无未决分歧而放行。
 
+### 执行方自提人工裁决行
+
+当执行方在产物 `## 未决问题` 中标记 `[needs-human-decision]` 时，必须在 task.md `## 审查分歧账本` upsert 对应 `HD-` 行：
+
+```markdown
+| HD-1 | plan | - | decision | needs-human-decision | plan.md#HD-1 |
+```
+
+- `stage` 填该决策产生的阶段：`analysis` / `plan` / `code`。
+- `round` 填 `-`，因为它不是 review finding 的握手轮次。
+- `severity` 固定填 `decision`。
+- `status` 初始填 `needs-human-decision`，因此会被现有 gate 阻塞。
+- 人工在 task.md `## 人工裁决` 段记录裁定后，把对应 `HD-` 行翻为 `human-decided`，`evidence` 指向该裁定记录。
+
 ## post-review commit 门禁（仅 code 阶段）
 
 - `review-code` 在最高轮报告中记录 `审查基线提交`（R，`git rev-parse HEAD`）和 `审查差异指纹`（F，完整工作区 diff fingerprint）。

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

@@ -37,3 +37,30 @@ Map user intent to the corresponding workflow command:
 - `complete-task`: update `status`, `current_step`, `completed_at`, `updated_at`, `agent_infra_version`
 - `block-task`: update `status`, `blocked_at`, `blocked_reason`, `updated_at`, `agent_infra_version`
 - `cancel-task`: update `status`, `cancelled_at`, `cancel_reason`, `updated_at`, `agent_infra_version`
+
+## 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.
+
+**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.
+
+- **started line** (written when the step begins): the action suffixes the existing base with ` [started]`, note is `started`:
+  `- {time} — **{base} [started]** by {agent} — started`
+- **done line** (written when the step completes, unchanged from today): the action is the base itself:
+  `- {time} — **{base}** by {agent} — {completion summary}`
+- `{base}` is that skill's existing done action text, including `(Round {N})` (e.g. `Plan Task (Round 1)`). started and done must share the same `{base}` to pair.
+
+**Pairing and rendering** (`ai task log`): a started entry pairs with the next same-`{base}` done entry onto one row (repeated executions of the same base pair FIFO by ascending time). The STARTED column shows the start time, DONE the completion time; started with no done = in progress (DONE shows `(in progress)`); done with no started (legacy logs) = a standalone completed row. All three shapes are valid and never error.
+
+**Human counts** (`ai task log`): review step rows fold two human counts into the NOTE verdict text, comma-separated, right after `blockers/major/minor`, localized to the task language (English `Manual-verify: {e}, Human-decision: {h}`; Chinese `人工校验点：{e}, 人工裁决：{h}`). `Human-decision` (`{h}`) maps canonical step prefixes (`Review Analysis` / `Review Plan` / `Review Code`) to `analysis` / `plan` / `code`, then counts current rows in `## Review Disagreement Ledger` / `## 审查分歧账本` for that stage with `status ∈ {needs-human-decision, human-decided}`. `Manual-verify` (`{e}`) parses `(+ {n} env-blocked)` from the review done note (de-duplicated from the display), defaulting to `0`. Non-review rows carry no human counts.
+
+**Gate** (`checkActivityLog`): when computing the "latest action / freshness" it skips `[started]` lines (ascending-order and format checks still cover every line), so a started marker never satisfies a skill's `expected_action_pattern`.
+
+**Skills that write started**: every workflow skill that **appends entries to a task's `## Activity Log`** writes started, so the STARTED column stays uniformly complete across the whole `ai task log` table. Two forms, depending on whether task.md already exists:
+
+- **Standard form (task.md already exists)** — append the started line when that round's real work begins (after prerequisites, before the first artifact action) and the done line on completion:
+  `analyze-task`, `plan-task`, `code-task`, `review-analysis`, `review-plan`, `review-code`, `commit`, `complete-task`, `create-pr`, `watch-pr`, `block-task`, `cancel-task`, `restore-task`, `close-codescan`, `close-dependabot`.
+- **Deferred form (the skill creates task.md, so there is no file to write to at the start)** — capture `started_at` in memory before running, then when writing the Activity Log at the end, **append both lines at once** (started line uses `started_at`, done line uses the completion time):
+  `create-task`, `import-issue`, `import-codescan`, `import-dependabot`.
+
+**Exceptions**: read-only inspection skills that do not represent real progress (e.g. `check-task`) do not write started. A bare operation with no task.md context (e.g. a `commit` not tied to a task) likewise skips it.

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

@@ -37,3 +37,34 @@
 - `complete-task`：更新 `status`、`current_step`、`completed_at`、`updated_at`、`agent_infra_version`
 - `block-task`：更新 `status`、`blocked_at`、`blocked_reason`、`updated_at`、`agent_infra_version`
 - `cancel-task`：更新 `status`、`cancelled_at`、`cancel_reason`、`updated_at`、`agent_infra_version`
+
+## Activity Log started / done 双标记约定（单一事实源）
+
+> 本节是 started/done 双标记的唯一权威定义。各 SKILL、渲染器（`lib/task/commands/log.ts`）、
+> 校验脚本（`.agents/scripts/validate-artifact.js`）的相关行为都以本节为准；改动任一端时同步本节。
+
+**行语法不变**：started 与 done 都沿用既有条目语法
+`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **{action}** by {agent} — {note}`，因此解析正则
+（`log.ts:ENTRY_RE` 与 `validate-artifact.js:ACTIVITY_LOG_PATTERN`）无需改动。
+
+- **started 行**（步骤开始时写）：action 在既有基名末尾加后缀 ` [started]`，note 用 `started`：
+  `- {time} — **{基名} [started]** by {agent} — started`
+- **done 行**（步骤完成时写，与现状一致）：action 即基名本身：
+  `- {time} — **{基名}** by {agent} — {完成说明}`
+- `{基名}` 指该 SKILL 既有 done 条目的 action 文本，含 `(Round {N})`（如 `Plan Task (Round 1)`）。
+  started 与 done 共用同一 `{基名}` 才能配对。
+
+**配对与渲染**（`ai task log`）：按 `{基名}` 把 started 与其后最近的同名 done 配成一行（同基名多次执行按时间升序 FIFO 配对）。STARTED 列显示 started 时间、DONE 列显示 done 时间；只有 started 无 done = 进行中（DONE 显示 `(in progress)`）；只有 done 无 started（历史日志）= 单态完成行。三种形态都合法、不报错。
+
+**人工计数**（`ai task log`）：审查步骤行把两项人工计数并入 NOTE 的 verdict 文本，逗号分隔、紧随 `blockers/major/minor`，按 task 语言本地化（中文 `人工校验点：{e}, 人工裁决：{h}`；英文 `Manual-verify: {e}, Human-decision: {h}`）。`人工裁决`（`{h}`）按 canonical 步骤名前缀（`Review Analysis` / `Review Plan` / `Review Code`）映射到 `analysis` / `plan` / `code`，统计 `## 审查分歧账本` 中对应阶段 `status ∈ {needs-human-decision, human-decided}` 的当前累计数量；`人工校验点`（`{e}`）解析 review done note 中的 `(+ {n} env-blocked)`（解析后从展示中去重），缺失为 `0`。非审查步骤不附加人工计数。
+
+**gate**（`checkActivityLog`）：计算「最新 action / freshness」时跳过 `[started]` 行（升序与格式校验仍覆盖全部行），故 started 标记不会污染各 SKILL 的 `expected_action_pattern`。
+
+**写 started 的 SKILL**：所有**会向某个任务的 `## 活动日志` 追加条目**的工作流 SKILL 都写 started，保证 `ai task log` 整张表的 STARTED 列一致完整。两种写法按技能是否已有 task.md 区分：
+
+- **常规写法（task.md 已存在）**——在「该轮实质工作开始时」（前置条件确认后、第一个产出动作前）追加 started 行，完成时写 done 行：
+  `analyze-task`、`plan-task`、`code-task`、`review-analysis`、`review-plan`、`review-code`、`commit`、`complete-task`、`create-pr`、`watch-pr`、`block-task`、`cancel-task`、`restore-task`、`close-codescan`、`close-dependabot`。
+- **延迟补写（本技能创建 task.md，开始时无文件可写）**——开始执行前先在内存记录 `started_at`，最后写活动日志时**一次性补两条**（started 行用 `started_at`、done 行用完成时间）：
+  `create-task`、`import-issue`、`import-codescan`、`import-dependabot`。
+
+**例外**：`check-task` 等只读巡检类、不代表实质工作推进的技能不写 started。无 task.md 上下文的纯操作（如无关联任务的 `commit`）同样跳过。

package/templates/.agents/scripts/validate-artifact.js

@@ -38,6 +38,10 @@ const DEFAULT_FRESHNESS_MINUTES = 30;
 const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2})?$/;
 const AGENT_INFRA_VERSION_PATTERN = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 const ACTIVITY_LOG_PATTERN = /^- (\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2})?) — \*\*(.+?)\*\* by (.+?) — (.+)$/;
+// Start markers (action suffixed with ` [started]`) are excluded from the
+// "latest action" / freshness computation so a step's in-flight marker never
+// satisfies a skill's expected_action_pattern; the matching done entry does.
+const ACTIVITY_LOG_STARTED_RE = /\s*\[started\]\s*$/;
 const BRANCH_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 // Review disagreement ledger (see .agents/rules/review-handshake.md).
@@ -462,8 +466,13 @@ function checkActivityLog({ taskDir, config }) {
     }
 
     previousTimestamp = timestamp;
-    latestTimestamp = timestamp;
-    latestAction = action;
+    // Ascending order is checked over every entry, but a `[started]` marker is
+    // not a terminal action: keep latestAction/latestTimestamp on the most
+    // recent done entry so expected_action_pattern and freshness see it.
+    if (!ACTIVITY_LOG_STARTED_RE.test(action)) {
+      latestTimestamp = timestamp;
+      latestAction = action;
+    }
   }
 
   if (config.expected_action_pattern && !new RegExp(config.expected_action_pattern).test(latestAction)) {

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

@@ -1,6 +1,8 @@
 ---
 name: analyze-task
-description: "Analyze a task and produce a requirements document"
+description: >
+  Analyze a task and produce a requirements document.
+  Use when you need to understand a task's requirements, scope, and risks before designing a solution.
 ---
 
 # Analyze Task
@@ -31,6 +33,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 prerequisites pass 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} — **Analyze Task (Round {N}) [started]** by {agent} — started
+```
+
+`ai task log` pairs it with the done entry written on completion (step 7) 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
@@ -172,6 +184,7 @@ Create `.agents/workspace/active/{task-id}/{analysis-artifact}`.
 ## Open Questions
 
 > If there are unresolved questions for human review, list them here; omit this section if there are none.
+> Mark key design decisions with `[needs-human-decision]` and write `HD-` ledger rows according to `.agents/rules/no-mid-flow-questions.md`.
 
 - {open question}
 

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

@@ -1,6 +1,8 @@
 ---
 name: analyze-task
-description: "分析任务并输出需求分析文档"
+description: >
+  分析任务并输出需求分析文档。
+  当需要在动手设计前厘清某个任务的需求、影响范围与风险时使用。
 ---
 
 # 分析任务
@@ -31,6 +33,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} — **Analyze Task (Round {N}) [started]** by {agent} — started
+```
+
+`ai task log` 会把它与步骤完成时（步骤 7）写入的 done 条目配对成一行（进行中 → 已完成）。格式与配对规则见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行步骤
 ### 1. 验证前置条件
 
@@ -171,6 +183,7 @@ tail .agents/workspace/active/{task-id}/task.md
 ## 未决问题
 
 > 如有需要人工裁定的未决问题，列在此处；没有则可省略本段。
+> 关键设计决策按 `.agents/rules/no-mid-flow-questions.md` 的判据标记 `[needs-human-decision]` 并回写 `HD-` 账本行。
 
 - {未决问题}
 

package/templates/.agents/skills/archive-tasks/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: archive-tasks
-description: "Archive completed tasks into a date-organized workspace directory"
+description: >
+  Archive completed tasks into a date-organized workspace directory.
+  Use when completed tasks have accumulated and you want to tidy them into the date-organized archive.
 ---
 
 # Archive Completed Tasks

package/templates/.agents/skills/archive-tasks/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: archive-tasks
-description: "归档已完成任务到按日期组织的目录"
+description: >
+  归档已完成任务到按日期组织的目录。
+  当已完成任务在 completed 目录堆积、需要整理归档时使用。
 ---
 
 # 归档已完成任务

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

@@ -1,6 +1,8 @@
 ---
 name: block-task
-description: "Mark a task as blocked and record the reason"
+description: >
+  Mark a task as blocked and record the reason.
+  Use when a task cannot proceed because of an external blocker and you need to park it with a reason.
 ---
 
 # Block Task
@@ -23,6 +25,16 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 > 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} — **Block Task [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`.
+
 ## Steps
 
 ### 1. Verify Task Exists

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

@@ -1,6 +1,8 @@
 ---
 name: block-task
-description: "标记任务为阻塞状态并记录原因"
+description: >
+  标记任务为阻塞状态并记录原因。
+  当任务因外部阻塞无法推进、需要挂起并记录原因时使用。
 ---
 
 # 标记任务阻塞
@@ -23,6 +25,16 @@ description: "标记任务为阻塞状态并记录原因"
 
 > 如果 `{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} — **Block Task [started]** by {agent} — started
+```
+
+`ai task log` 会把它与完成时写入的 done 条目配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行步骤
 ### 1. 验证任务存在
 

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
@@ -17,6 +19,16 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 > 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} — **Cancel Task [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`.
+
 ## Steps
 
 ### 1. Verify Task Exists

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

@@ -1,6 +1,8 @@
 ---
 name: cancel-task
-description: "取消不再需要的任务并转移"
+description: >
+  取消不再需要的任务并转移。
+  当某个任务不再需要、应从 active 工作中撤下时使用。
 ---
 
 # 取消任务
@@ -17,6 +19,16 @@ description: "取消不再需要的任务并转移"
 
 > 如果 `{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} — **Cancel Task [started]** by {agent} — started
+```
+
+`ai task log` 会把它与完成时写入的 done 条目配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行步骤
 ### 1. 验证任务存在
 
@@ -137,7 +149,7 @@ ai sandbox rm {branch}
 
 下一步 - 查看已转移任务：
   - Claude Code / OpenCode：/check-task {task-ref}
-  - Gemini CLI：/{{project}}:check-task {task-ref}
+  - Gemini CLI：/agent-infra:check-task {task-ref}
   - Codex CLI：$check-task {task-ref}
 ```
 

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`