@fitlab-ai/agent-infra 0.7.6 → 0.8.0

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -22,11 +22,11 @@
 
 从 `task.md` 提取以下字段：
 
-- 任务标题（首个 `# ` 标题，去掉 `任务：` / `Task:` 前缀）
-- `## Description` / `## 描述` 段落
-- `## Requirements` / `## 需求` 段落
+- 任务标题（首个 `# ` 标题，去掉 `任务：` / `Task:` 前缀）—— 用于构造 Issue 标题
 - frontmatter 中的 `type` 与（可选的）`milestone`
 
+> Issue **正文**不在此处手工提取。正文由 §3 调用 `ai task issue-body` 命令从 `## 描述` / `## 需求` 段确定性生成，调用方不得自行拼装。
+
 构造 Issue 标题：
 
 | task.md `type` | Conventional Commits type |
@@ -41,45 +41,35 @@ scope 推断：从 `.agents/.airc.json` 的 `labels.in` 字段读取已知模块
 
 ### 3. 构建 Issue 正文
 
+> **机械化边界（必须遵守）**：Issue 正文一律由 `ai task issue-body` 命令确定性生成；调用方只把命令 stdout 作为 `gh issue create` 的 `--body-file` 传入，**不得**自行拼装、改写或截断正文。命令只输出 task 标题 / `## 描述` / `## 需求` 对应内容，task.md 其余脚手架段落永不进入 body。
+
 Issue 模板检测：按 `.agents/rules/issue-pr-commands.md` 的 "Issue 模板检测" 规则扫描 `.github/ISSUE_TEMPLATE/*.yml`（排除 `config.yml`）。
 
 #### 场景 A：检测到匹配模板
 
 按模板顶层 `name` 与任务类型挑选最匹配的 form（如任务 `type: bugfix` 优先选名称含 `bug` 的模板）；找不到匹配时，回退到通用 form（如 `other.yml`），仍找不到时取目录中第一个 form。
 
-按 `.agents/rules/issue-pr-commands.md` 中 "Issue 模板检测" 章节的字段处理规则填充 form：
-
-- `textarea` / `input` 字段：使用 `attributes.label` 作为 markdown 标题，从 task.md 取值
-- `markdown` 字段：跳过（说明文案）
-- `dropdown` / `checkboxes` 字段：跳过
+确定模板文件 `{form-path}` 后，由命令按该 Issue Form 渲染最终正文，并写入正文文件 `{body-file}` 供 §5 使用：
 
-字段值映射（建议）：
-
-| 模板字段提示 | task.md 来源 |
-|---|---|
-| `summary`, `title` | 任务标题 |
-| `description`, `problem`, `what happened`, `issue-description`, `current-content` | 任务描述 |
-| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | 需求列表（已勾选与未勾选混合，原样保留） |
-| 其它 `textarea` / `input` 字段 | 任务描述；缺失时填 `N/A` |
+```bash
+ai task issue-body {task-id} --template "{form-path}" > "{body-file}"
+```
 
-任何字段在 task.md 中找不到合适值时，写入 `N/A`。
+命令跳过 `markdown` / `dropdown` / `checkboxes` 字段，对 `input` / `textarea` 字段以 `attributes.label` 作标题、按字段 `id` 确定性填入 task 标题 / 描述 / 需求，无可靠映射源的字段填 `N/A`（字段映射表是命令内的单一真源，不在本规则重述）。命令退出码非 0（文件缺失 / 非法 YAML / 无 `body`）时，改用场景 B 命令重新生成 `{body-file}`。
 
 #### 场景 B：无模板或解析失败
 
-回退到默认正文：
-
-```markdown
-## Description
+由命令输出默认正文（仅 `## 描述` + `## 需求`，复选框逐字保留，缺失段落填 `N/A`），写入 `{body-file}`：
 
-{任务描述；缺失时填 N/A}
+```bash
+ai task issue-body {task-id} > "{body-file}"
+```
 
-## Requirements
+#### 红线：禁止把整份 task.md 当 body
 
-- [ ] {requirement-1}
-- [ ] {requirement-2}
-```
+无论场景 A / B，body 只能来自 `ai task issue-body` 的 stdout，**只含 描述 + 需求两段内容**（场景 A 为按模板字段映射后的等价内容）。
 
-需求列表为空时，整段写 `N/A`。
+错误示范（❌ 禁止）：把含 `## 分析` / `## 设计` / `## 实现备注` / `## 审查反馈` / `## 审查分歧账本` / `## 人工裁决` / `## 活动日志` / `## 完成检查清单` 等脚手架段落、以及 `#XXX` 占位的整份 task.md 直接作为 Issue body。这些段落只走 `sync-issue:{task-id}:task` 评论，绝不进 body。
 
 ### 4. 解析 labels / Issue Type / milestone
 
@@ -137,17 +127,18 @@ Issue 模板检测：按 `.agents/rules/issue-pr-commands.md` 的 "Issue 模板
 
 ### 5. 调用 GitHub CLI 创建 Issue
 
-按 `.agents/rules/issue-pr-commands.md` 中的 "创建 Issue" 命令执行：
+按 `.agents/rules/issue-pr-commands.md` 中的 "创建 Issue" 命令执行；正文统一用 §3 生成的 `{body-file}`，覆盖通用命令的 `--body`：
 
 ```bash
 gh issue create -R "$upstream_repo" \
   --title "{title}" \
-  --body "{body}" \
+  --body-file "{body-file}" \
   --assignee @me \
   {label-args} \
   {milestone-arg}
 ```
 
+- `{body-file}` 为 §3 由 `ai task issue-body` 生成的正文文件；**不得**改用 `--body` 自行拼装正文
 - `{label-args}` 由 §4 计算结果展开为多个 `--label "..."`；为空则整体省略
 - `{milestone-arg}` 仅当 `has_triage=true` 且 milestone 非空时展开为 `--milestone "..."`；否则整体省略
 - `--assignee @me` 不做权限预判，失败时静默跳过

package/templates/.agents/rules/issue-fields.github.en.md

@@ -29,7 +29,7 @@ Localized option input may be normalized before writing:
 | `中` | `Medium` |
 | `低` | `Low` |
 
-AI agents may infer `priority` and `effort` from the title and description when creating or refining tasks, but must keep date fields empty unless the user or source Issue provides explicit dates. Human edits in `task.md` take precedence.
+AI agents may infer `priority` and `effort` from the title and description when creating or refining tasks. Date fields are factual, not estimated: `start_date` is written by the analyze stage (the analysis start date) and `target_date` by the complete stage (the completion date). Human edits in `task.md` take precedence.
 
 ## GraphQL Reference
 

package/templates/.agents/rules/issue-fields.github.zh-CN.md

@@ -29,7 +29,7 @@
 | `中` | `Medium` |
 | `低` | `Low` |
 
-AI agent 在创建或修订任务时可根据标题与描述推断 `priority` 和 `effort`，但除非用户或来源 Issue 明确提供日期，否则必须保持日期字段为空。`task.md` 中人工填写的值优先。
+AI agent 在创建或修订任务时可根据标题与描述推断 `priority` 和 `effort`。日期字段为事实值、不估算：`start_date` 由 analyze 阶段写入（= 分析开始日），`target_date` 由 complete 阶段写入（= 完成日）。`task.md` 中人工填写的值优先。
 
 ## GraphQL 参考
 

package/templates/.agents/rules/issue-pr-commands.github.en.md

@@ -186,6 +186,12 @@ List PRs:
 gh pr list --state {state} --base {base-branch} --json number,title,url,headRefName,baseRefName
 ```
 
+Find the open PR whose head is the current branch (used by the `commit` push wrap-up):
+
+```bash
+gh pr list --head "{branch}" --state open --json number,url --jq '.[0].url // empty'
+```
+
 Create a PR:
 
 ```bash

package/templates/.agents/rules/issue-pr-commands.github.zh-CN.md

@@ -186,6 +186,12 @@ gh pr view {pr-number} --json number,title,body,labels,state,milestone,url,files
 gh pr list --state {state} --base {base-branch} --json number,title,url,headRefName,baseRefName
 ```
 
+按 head 分支查询当前分支是否存在开放 PR（`commit` 推送收尾用）：
+
+```bash
+gh pr list --head "{branch}" --state open --json number,url --jq '.[0].url // empty'
+```
+
 创建 PR：
 
 ```bash

package/templates/.agents/rules/next-step-output.en.md

@@ -1,9 +1,10 @@
 # Next-Step Output Rule
 
-This file defines two **independent** rules for a skill's "notify-user / Next steps" output; read this file before rendering the final output and apply both:
+This file defines three **independent** rules for a skill's "notify-user / Next steps" output (the 3rd applies to review-* only); read this file before rendering the final output and apply whichever rules apply:
 
 1. **Next-step output structure**: how "Next steps" commands and the "Task info" block present the task ID (placeholders / short-id lookup / fallback).
 2. **Agent output trailing line (Completed at)**: the **very last line** of user-facing output, **independent of the "Next steps" block**, applying to normal / error / early-return paths alike.
+3. **Pending human-decision pre-block**: applies only to `review-analysis` / `review-plan` / `review-code` when this stage has pending rulings (`{h} > 0`) — expand the pending items before the "Next steps" commands and prompt to resolve them first.
 
 ## Placeholder semantics
 
@@ -60,3 +61,31 @@ Completed at: YYYY-MM-DD HH:mm:ss
 - Value command (local timezone, no offset): `date "+%Y-%m-%d %H:%M:%S"`
 - Position: it must be the last line of the entire user-facing output, after all "Next steps" commands. If a scenario has a conditional reminder line after the commands (e.g. the env-blocked reminder), the completion line goes after that reminder.
 - This line is for terminal scanning only; it is never written to any artifact file or Issue/PR comment. The single source of truth for completion time remains the Activity Log in task.md.
+
+## Pending human-decision pre-block (review-* only, when {h} > 0)
+
+This section is a **third standalone rule, co-equal with the two above**, used only by the "notify-user / report conclusion" step of `review-analysis` / `review-plan` / `review-code`.
+
+`{h}` has the same meaning as the count line in each review skill's `reference/output-templates.md`: the number of rows in task.md `## 审查分歧账本` (Review Disagreement Ledger) for **this stage** (`stage ∈ {analysis|plan|code}`) whose `status = needs-human-decision` — **pending items only, excluding rows already `human-decided`**.
+
+- **`{h} = 0`**: do not emit this block; render "Next steps" exactly as the selected output-templates scenario.
+- **`{h} > 0`**: insert the block below **before** the selected scenario's "Next steps - <stage>" commands; the next-stage commands are still listed after the block.
+
+```text
+⚠️ Pending human decisions ({h}) — please rule on each before continuing to the next stage:
+  - {ledger-id} ({stage}/{severity}): {summary}
+    Location: the matching row in task.md `## 审查分歧账本` · Evidence: {evidence}
+  …(one entry per status=needs-human-decision row of this stage in task.md `## 审查分歧账本`)
+
+View details:
+  - All pending decisions: ai task decisions {task-ref}
+  - A single item's full background/options/impact/recommendation: ai task decisions {task-ref} <ordinal|HD-id>
+
+To resolve:
+  1. In the task.md `## 人工裁决` section, record your ruling and rationale for each item above.
+  2. Flip the status of the matching row in `## 审查分歧账本` from `needs-human-decision` to `human-decided`.
+
+Note: until all those rows are flipped to `human-decided`, running the next-stage command directly will be blocked by gates such as complete-task (`needs-human-decision` is non-terminal). The next-stage commands are still listed below for use after the decisions are made.
+```
+
+Field values: `{ledger-id}` / `{stage}` / `{severity}` / `{evidence}` come from the same-named columns of the matching `## 审查分歧账本` row; `{summary}` comes from the artifact anchor referenced by `{evidence}` (e.g. the decision title at `plan.md#HD-1`), falling back to a one-line summary of the finding when no anchor title exists.

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,31 @@ 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 行一条）
+
+查看详情：
+  - 全部待裁决项：ai task decisions {task-ref}
+  - 单项完整背景/选项/影响/建议：ai task decisions {task-ref} <序号|HD-id>
+
+完成裁决：
+  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

@@ -55,7 +55,10 @@ For every SKILL execution context not covered by any exemption above, the defaul
 
 ## 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`.
+When an open question is a key design decision that needs human judgment, the executor must:
+
+1. Write the decision's **detail block** (background / options / impact / recommendation) into the artifact's `## 人工裁决待办` (Pending Human Decisions) section, with a heading like `### HD-N：<title> [needs-human-decision]`; ordinary assumptions / open questions still go under `## Assumptions` / `## Open Questions` (`## 假设` / `## 未决问题`), and `## Open Questions` may keep a one-line pointer to the matching `### HD-N`.
+2. Upsert the matching `HD-` row in task.md `## Review Disagreement Ledger` according to `.agents/rules/review-handshake.md`, with `evidence` pointing to the stable anchor `<artifact>#HD-N`. The `HD-N` number is **globally unique** (scan existing `HD-(\d+)` in the ledger and take max+1, monotonically increasing across analysis / plan / code, never reused); see review-handshake.md for the allocation rule.
 
 Use these checks together:
 
@@ -64,6 +67,8 @@ Use these checks together:
 - **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.
 
+> Use `ai task decisions <task-ref>` to view all pending decisions of a task and their detail blocks.
+
 ## Human Review Checkpoint Semantics
 
 A mandatory human review checkpoint means:
@@ -71,7 +76,7 @@ A mandatory human review checkpoint means:
 - Stop after producing the artifact: once the skill finishes an artifact such as `plan.md`, end the current invocation and wait for the user to explicitly trigger the next skill command
 - Do not pause mid-process to ask for input: do not insert interruptions such as "Do you prefer option A or B?" between execution steps
 
-If a key decision needs human judgment during execution, follow the assumptions and open questions rule above: record it in the artifact's "Open Questions" / `未决问题` section for the user to address at the review checkpoint.
+If a key decision needs human judgment during execution, follow the "Key Design Decision Marking And Ledgering" rule above: write the detail block into the artifact's `## 人工裁决待办` (Pending Human Decisions) section as `### HD-N` and upsert the `HD-` ledger row, for the user to address at the review checkpoint; ordinary open questions still go to `## Open Questions` / `未决问题`.
 
 ## Anchor Location
 

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

@@ -55,7 +55,10 @@
 
 ## 关键设计决策标记与落账
 
-当未决问题属于需要人工裁定的关键设计决策时，执行方必须在该条目前标记 `[needs-human-decision]`，并按 `.agents/rules/review-handshake.md` 在 task.md `## 审查分歧账本` 写入 `HD-` 行。
+当未决问题属于需要人工裁定的关键设计决策时，执行方必须：
+
+1. 把该决策的**详情块**（背景 / 选项 / 影响 / 推荐）写入产物的 `## 人工裁决待办` 段，标题形如 `### HD-N：<标题> [needs-human-decision]`；普通假设 / 未决问题仍分别写 `## 假设` / `## 未决问题`（`## Assumptions` / `## Open Questions`），`## 未决问题` 可保留一行指针指向对应 `### HD-N`。
+2. 按 `.agents/rules/review-handshake.md` 在 task.md `## 审查分歧账本` upsert 对应 `HD-` 行，evidence 指向稳定锚点 `<artifact>#HD-N`。`HD-N` 编号**全局唯一**（扫描账本已有 `HD-(\d+)` 取 max+1，跨 analysis / plan / code 单调递增、禁止复用），分配规则详见 review-handshake.md。
 
 判定时同时使用以下检查：
 
@@ -64,6 +67,8 @@
 - **小影响豁免**：若它只是局部、可逆、低成本的执行细节，写入 `## 假设` 即可，不升级为人工裁决。
 - **兜底**：无法判断是否关键时按关键处理；`review-*` 需要复核执行方是否漏标应升级的 `[needs-human-decision]`。
 
+> 用户可用 `ai task decisions <task-ref>` 查看某任务全部待裁决项及其详情块。
+
 ## 人工审查检查点语义
 
 「强制性人工审查检查点」（mandatory human review checkpoint）的语义是：
@@ -71,7 +76,7 @@
 - **产出后停止**：技能完成产物（如 `plan.md`）后立即结束本轮调用，等待用户主动触发下一个技能命令
 - **不是过程中暂停征求意见**：不允许在执行步骤之间插入「请问您倾向 A 还是 B？」之类的中断
 
-如果在执行过程中发现需要用户裁定的关键决策，按上文「假设与未决问题」处理，记录到产物的「未决问题」/`Open Questions` 段落，由用户在审查检查点统一回应。
+如果在执行过程中发现需要用户裁定的关键决策，按上文「关键设计决策标记与落账」处理：详情块写入产物 `## 人工裁决待办` 的 `### HD-N`、回写 `HD-` 账本行，由用户在审查检查点统一回应；普通未决问题仍写 `## 未决问题` / `Open Questions`。
 
 ## 锚点位置
 

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

@@ -67,18 +67,22 @@ The single source of truth for disagreement state is the fixed `## 审查分歧
 
 ### 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`:
+When an executor judges an item to be a key design decision that needs human ruling, it must write the detail block (background / options / impact / recommendation) into the artifact's `## 人工裁决待办` (Pending Human Decisions) section with a heading like `### HD-N：<title> [needs-human-decision]`, and upsert the matching `HD-` row in task.md `## Review Disagreement Ledger`:
 
 ```markdown
 | HD-1 | plan | - | decision | needs-human-decision | plan.md#HD-1 |
 ```
 
+- `id`: the `HD-N` number is **globally unique**. When adding a row, scan every `HD-(\d+)` in the ledger and take max+1 (start at `HD-1` when none exist); it increases monotonically across `analysis` / `plan` / `code` and is **never reused**, so selecting by `HD-id` is unambiguous.
 - `stage` is the stage where the decision arose: `analysis` / `plan` / `code`.
 - `round` is `-` because this is not a review-finding handshake round.
 - `severity` is always `decision`.
 - `status` starts as `needs-human-decision`, so the existing gate blocks it.
+- `evidence` points to the stable anchor `<artifact>#HD-N` (e.g. `plan-r2.md#HD-1`), not a drift-prone line number.
 - After a human records the ruling in task.md `## Human Rulings`, flip the matching `HD-` row to `human-decided` and point `evidence` to that ruling.
 
+> View: `ai task decisions <task-ref>` lists all pending decisions; `ai task decisions <task-ref> <ordinal|HD-id>` expands a single item's detail block. This command shares the ledger parser `lib/task/ledger.ts` with `ai task log`; the gate parser in `.agents/scripts/validate-artifact.js` is a separate implementation and the two must be kept semantically in sync by hand.
+
 ## 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

@@ -67,18 +67,22 @@
 
 ### 执行方自提人工裁决行
 
-当执行方在产物 `## 未决问题` 中标记 `[needs-human-decision]` 时，必须在 task.md `## 审查分歧账本` upsert 对应 `HD-` 行：
+当执行方判定某项为需人工裁定的关键设计决策时，必须把详情块（背景 / 选项 / 影响 / 推荐）写入产物的 `## 人工裁决待办` 段，标题形如 `### HD-N：<标题> [needs-human-decision]`，并在 task.md `## 审查分歧账本` upsert 对应 `HD-` 行：
 
 ```markdown
 | HD-1 | plan | - | decision | needs-human-decision | plan.md#HD-1 |
 ```
 
+- `id`：`HD-N` 编号**全局唯一**。新增行时扫描账本中所有 `HD-(\d+)`，取最大值 + 1（账本无 `HD-` 行则从 `HD-1` 起）；跨 `analysis` / `plan` / `code` 单调递增，**禁止复用**既有编号，避免按 `HD-id` 定位时歧义。
 - `stage` 填该决策产生的阶段：`analysis` / `plan` / `code`。
 - `round` 填 `-`，因为它不是 review finding 的握手轮次。
 - `severity` 固定填 `decision`。
 - `status` 初始填 `needs-human-decision`，因此会被现有 gate 阻塞。
+- `evidence` 指向稳定锚点 `<artifact>#HD-N`（如 `plan-r2.md#HD-1`），不依赖易漂移的行号。
 - 人工在 task.md `## 人工裁决` 段记录裁定后，把对应 `HD-` 行翻为 `human-decided`，`evidence` 指向该裁定记录。
 
+> 查看：`ai task decisions <task-ref>` 列出全部待裁决项；`ai task decisions <task-ref> <序号|HD-id>` 展开单项详情块。该命令的账本解析与 `ai task log` 共用 `lib/task/ledger.ts`；`.agents/scripts/validate-artifact.js` 的 gate 解析器是独立实现，二者语义须手工保持同步。
+
 ## post-review commit 门禁（仅 code 阶段）
 
 - `review-code` 在最高轮报告中记录 `审查基线提交`（R，`git rev-parse HEAD`）和 `审查差异指纹`（F，完整工作区 diff fingerprint）。

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

@@ -35,7 +35,7 @@ Map user intent to the corresponding workflow command:
 - `create-pr`: update `pr_number`, `updated_at`, `agent_infra_version`
 - `commit`: update `updated_at`, `agent_infra_version`; update `current_step` when needed (see `commit/reference/task-status-update.md`)
 - `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`
+- `block-task`: update `status`, `blocked_at`, `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)
@@ -52,6 +52,8 @@ Map user intent to the corresponding workflow command:
 
 **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`, with fixed English labels `Manual-verify: {e}, Human-decision: {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:

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

@@ -35,7 +35,7 @@
 - `create-pr`：更新 `pr_number`、`updated_at`、`agent_infra_version`
 - `commit`：更新 `updated_at`、`agent_infra_version`；必要时更新 `current_step`（详见 `commit/reference/task-status-update.md`）
 - `complete-task`：更新 `status`、`current_step`、`completed_at`、`updated_at`、`agent_infra_version`
-- `block-task`：更新 `status`、`blocked_at`、`blocked_reason`、`updated_at`、`agent_infra_version`
+- `block-task`：更新 `status`、`blocked_at`、`updated_at`、`agent_infra_version`
 - `cancel-task`：更新 `status`、`cancelled_at`、`cancel_reason`、`updated_at`、`agent_infra_version`
 
 ## Activity Log started / done 双标记约定（单一事实源）
@@ -56,6 +56,8 @@
 
 **配对与渲染**（`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`，固定英文标签 `Manual-verify: {e}, Human-decision: {h}`。`Human-decision`（`{h}`）按 canonical 步骤名前缀（`Review Analysis` / `Review Plan` / `Review Code`）映射到 `analysis` / `plan` / `code`，统计 `## 审查分歧账本` 中对应阶段 `status ∈ {needs-human-decision, human-decided}` 的当前累计数量；`Manual-verify`（`{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 区分：

package/templates/.agents/scripts/lib/post-review-commit.js

@@ -3,25 +3,22 @@ import path from "node:path";
 
 import { artifactName, maxRound } from "./review-artifacts.js";
 
-export const DEFAULT_POST_REVIEW_GLOBS = [
-  ".agents/skills",
-  ".agents/scripts",
-  ".agents/rules",
-  ".agents/workflows",
-  "bin",
-  "lib",
-  "src",
-  "templates"
-];
-
+// Paths excluded from the post-review coverage gate. Fail-closed: the gate
+// covers ALL tracked changes by default. This default denylist is EMPTY —
+// projects opt into exclusions explicitly via review.post_review_exclude_globs.
+export const DEFAULT_POST_REVIEW_EXCLUDES = [];
+
+// Returns git pathspecs selecting "all tracked changes except project excludes".
+// The leading ":/" makes coverage fail-closed (everything from the repo root);
+// each exclude becomes a top-level negative pathspec. Projects extend the
+// denylist via review.post_review_exclude_globs (union, deduped).
 export function resolvePostReviewGlobs(config = {}, reviewConfig = {}) {
-  if (Array.isArray(config.post_review_globs)) {
-    return config.post_review_globs;
-  }
-  if (Array.isArray(reviewConfig.post_review_globs)) {
-    return reviewConfig.post_review_globs;
-  }
-  return DEFAULT_POST_REVIEW_GLOBS;
+  const projectExcludes = [
+    ...(Array.isArray(reviewConfig.post_review_exclude_globs) ? reviewConfig.post_review_exclude_globs : []),
+    ...(Array.isArray(config.post_review_exclude_globs) ? config.post_review_exclude_globs : [])
+  ];
+  const excludes = [...new Set([...DEFAULT_POST_REVIEW_EXCLUDES, ...projectExcludes])];
+  return [":/", ...excludes.map((p) => `:(top,exclude)${p}`)];
 }
 
 export function findAuthoritativeReviewCodeArtifact(taskDir) {

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

@@ -316,6 +316,14 @@ function checkTaskMeta({ taskDir, config }) {
     return failResult("task-meta", "Expected cancelled_at to be present");
   }
 
+  if (config.require_start_date && isBlank(metadata.start_date)) {
+    return failResult("task-meta", "Expected start_date to be present");
+  }
+
+  if (config.require_target_date && isBlank(metadata.target_date)) {
+    return failResult("task-meta", "Expected target_date to be present");
+  }
+
   if (config.match_task_dir !== false) {
     const expectedTaskId = path.basename(taskDir);
     if (metadata.id !== expectedTaskId) {

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
@@ -110,10 +112,10 @@ Runs after Step 0 state check and Step 3 (questioning is an external-state actio
   1. Decide this round's question (consistent with 4.2):
      - if a `pending_question` already exists (the previous question is still unanswered) → restate that `pending_question`, do **not** modify it and do **not** increment `question_count`;
      - otherwise (no pending question) → pick the single highest-value question (acceptance criteria > scope > ambiguity) and write `## Brainstorming`: `status: asking`, `pending_question: <question>`, `question_count += 1`.
-  2. Update frontmatter: `current_step: requirement-analysis`, `assigned_to`, `updated_at`, `agent_infra_version` (read `.agents/rules/version-stamp.md` first).
+  2. Update frontmatter: `current_step: requirement-analysis`, `assigned_to`, `updated_at`, `agent_infra_version` (read `.agents/rules/version-stamp.md` first); if `start_date` is empty, also write today's date (`date +%F`) to satisfy the required `start_date` check at the requirement-analysis stage.
   3. Append to Activity Log: `- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Analyze Task (Brainstorming)** by {agent} — Asked Q{question_count}, awaiting answer`.
   4. Issue sync (when `issue_number` exists, skip on any failure): read `.agents/rules/issue-sync.md` first for upstream / permission detection; update only the **task comment** per the task.md comment sync rule; keep the `status` label at `pending-design-work`; do **not** publish an analysis artifact comment.
-  5. Verification (replaces the step 8 artifact gate): `node .agents/scripts/validate-artifact.js check task-meta .agents/workspace/active/{task-id} --skill analyze-task --format text` (the early-exit set `current_step: requirement-analysis`, so it should pass); also keep `rg -n 'Analyze Task \(Brainstorming\)' .agents/workspace/active/{task-id}/task.md` and the task-comment sync evidence. Do **not** run the artifact gate, nor `check activity-log` / `check platform-sync` (both bind to the analysis artifact path).
+  5. Verification (replaces the step 8 artifact gate): `node .agents/scripts/validate-artifact.js check task-meta .agents/workspace/active/{task-id} --skill analyze-task --format text` (the early-exit set `current_step: requirement-analysis` and wrote `start_date`, so it should pass); also keep `rg -n 'Analyze Task \(Brainstorming\)' .agents/workspace/active/{task-id}/task.md` and the task-comment sync evidence. Do **not** run the artifact gate, nor `check activity-log` / `check platform-sync` (both bind to the analysis artifact path).
   6. User output: show only the current **single question** plus how to answer/continue (re-trigger `analyze-task {task-ref}` with the answer), and append the `Completed at` line per `.agents/rules/next-step-output.md`.
   7. **STOP** and wait for the answer. The next trigger returns to this step.
 
@@ -182,10 +184,22 @@ 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`.
+> Ordinary open questions go here; for key design decisions (per `.agents/rules/no-mid-flow-questions.md`), put the detail block under `## 人工裁决待办` (Pending Human Decisions) as `### HD-N` instead, and keep only a one-line pointer here.
 
 - {open question}
 
+## 人工裁决待办
+
+> Write this section only when this round upgraded a `[needs-human-decision]` key design decision; omit otherwise.
+> One `### HD-N` block per item (`HD-N` is globally unique, see `.agents/rules/review-handshake.md`), and upsert the matching `HD-` row in task.md `## Review Disagreement Ledger` (evidence pointing to `{analysis-artifact}#HD-N`).
+
+### HD-{N}：{title} [needs-human-decision]
+
+- **Background**: {why it became a pending decision}
+- **Options**: {A / B / …}
+- **Impact**: {scope / boundaries / precedent}
+- **Recommendation**: {recommended option and rationale}
+
 ## Effort and Complexity Assessment
 - Complexity: {High/Medium/Low}
 - Risk level: {High/Medium/Low}

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

@@ -1,6 +1,8 @@
 ---
 name: analyze-task
-description: "分析任务并输出需求分析文档"
+description: >
+  分析任务并输出需求分析文档。
+  当需要在动手设计前厘清某个任务的需求、影响范围与风险时使用。
 ---
 
 # 分析任务
@@ -109,10 +111,10 @@ tail .agents/workspace/active/{task-id}/task.md
   1. 确定本轮要问的问题（与 4.2 保持一致）：
      - 若已存在 `pending_question`（上一问尚未得到答案）→ 复述该 `pending_question`，**不**修改它、**不**增加 `question_count`；
      - 否则（无待答问题）→ 选最高价值的一个问题（验收标准 > 范围 > 歧义），写入 `## Brainstorming`：`status: asking`、`pending_question: <问题>`、`question_count += 1`。
-  2. 更新 frontmatter：`current_step: requirement-analysis`、`assigned_to`、`updated_at`、`agent_infra_version`（先读 `.agents/rules/version-stamp.md`）。
+  2. 更新 frontmatter：`current_step: requirement-analysis`、`assigned_to`、`updated_at`、`agent_infra_version`（先读 `.agents/rules/version-stamp.md`）；若 `start_date` 为空，同时写入当日日期（`date +%F`），以满足 requirement-analysis 阶段 `start_date` 必填校验。
   3. 追加 Activity Log：`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Analyze Task (Brainstorming)** by {agent} — Asked Q{question_count}, awaiting answer`。
   4. Issue 同步（存在 `issue_number` 时，任一失败跳过）：先读 `.agents/rules/issue-sync.md` 完成 upstream / 权限检测；仅按 task.md 评论同步规则更新 **task 评论**；`status` label 维持 `pending-design-work`；**不**发布分析产物评论。
-  5. 校验（替代步骤 8 的 artifact gate）：`node .agents/scripts/validate-artifact.js check task-meta .agents/workspace/active/{task-id} --skill analyze-task --format text`（早退已置 `current_step: requirement-analysis`，预期通过）；并保留 `rg -n 'Analyze Task \(Brainstorming\)' .agents/workspace/active/{task-id}/task.md` 与 task 评论同步证据。**不**跑 artifact gate，也不跑 `check activity-log` / `check platform-sync`（二者绑定分析产物路径）。
+  5. 校验（替代步骤 8 的 artifact gate）：`node .agents/scripts/validate-artifact.js check task-meta .agents/workspace/active/{task-id} --skill analyze-task --format text`（早退已置 `current_step: requirement-analysis` 且已写入 `start_date`，预期通过）；并保留 `rg -n 'Analyze Task \(Brainstorming\)' .agents/workspace/active/{task-id}/task.md` 与 task 评论同步证据。**不**跑 artifact gate，也不跑 `check activity-log` / `check platform-sync`（二者绑定分析产物路径）。
   6. 用户输出：只展示当前**单个问题** + 如何回答/继续（再次触发 `analyze-task {task-ref}` 并附答案），并按 `.agents/rules/next-step-output.md` 在末行追加 `Completed at`。
   7. **STOP**，等待回答。下一次触发回到本步骤。
 
@@ -181,10 +183,22 @@ tail .agents/workspace/active/{task-id}/task.md
 ## 未决问题
 
 > 如有需要人工裁定的未决问题，列在此处；没有则可省略本段。
-> 关键设计决策按 `.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` 块（`HD-N` 全局唯一，见 `.agents/rules/review-handshake.md`），并在 task.md `## 审查分歧账本` upsert 对应 `HD-` 行（evidence 指向 `{analysis-artifact}#HD-N`）。
+
+### HD-{N}：{标题} [needs-human-decision]
+
+- **背景**：{为何成为待裁决项}
+- **选项**：{A / B / …}
+- **影响**：{范围 / 边界 / 先例}
+- **推荐**：{推荐选项及理由}
+
 ## 工作量和复杂度评估
 - 复杂度：{高/中/低}
 - 风险等级：{高/中/低}

package/templates/.agents/skills/analyze-task/config/verify.en.json

@@ -13,7 +13,8 @@
         "current_step",
         "assigned_to"
       ],
-      "expected_step": "requirement-analysis"
+      "expected_step": "requirement-analysis",
+      "require_start_date": true
     },
     "artifact": {
       "file_pattern": "analysis.md|analysis-r{N}.md",

package/templates/.agents/skills/analyze-task/config/verify.zh-CN.json

@@ -13,7 +13,8 @@
         "current_step",
         "assigned_to"
       ],
-      "expected_step": "requirement-analysis"
+      "expected_step": "requirement-analysis",
+      "require_start_date": true
     },
     "artifact": {
       "file_pattern": "analysis.md|analysis-r{N}.md",

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

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

@@ -1,6 +1,8 @@
 ---
 name: block-task
-description: "标记任务为阻塞状态并记录原因"
+description: >
+  标记任务为阻塞状态并记录原因。
+  当任务因外部阻塞无法推进、需要挂起并记录原因时使用。
 ---
 
 # 标记任务阻塞