@fitlab-ai/agent-infra 0.7.7 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,8 @@
     "installer"
   ],
   "dependencies": {
-    "@clack/prompts": "1.5.1",
+    "@clack/prompts": "1.6.0",
+    "@larksuiteoapi/node-sdk": "^1.68.0",
     "cross-spawn": "^7.0.6",
     "picocolors": "1.1.1",
     "semver": "^7.8.1",
@@ -63,11 +64,14 @@
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^25.9.1",
+    "@types/node": "^24.0.0",
     "@types/semver": "^7.7.1",
     "typescript": "~6.0"
   },
   "optionalDependencies": {
     "@lydell/node-pty": "^1.2.0-beta.12"
+  },
+  "overrides": {
+    "axios": "1.18.1"
   }
 }

package/templates/.agents/QUICKSTART.zh-CN.md

@@ -47,8 +47,8 @@ cp .agents/templates/task.md .agents/workspace/active/task-001.md
 
 ```yaml
 id: task-001
-type: feature          # feature | bugfix | refactor | docs | review
-status: open           # open | in-progress | review | blocked | completed
+type: feature          # feature | bugfix | refactor | docs | chore
+status: active         # active | blocked | completed
 assigned_to: claude    # claude | codex | gemini | opencode | human
 ```
 

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/next-step-output.en.md

@@ -77,6 +77,10 @@ This section is a **third standalone rule, co-equal with the two above**, used o
     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`.

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

@@ -77,6 +77,10 @@ Completed at: YYYY-MM-DD HH:mm:ss
     位置：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`。

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,7 +52,7 @@ 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`, 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.
+**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`.
 

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,7 +56,7 @@
 
 **配对与渲染**（`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`。非审查步骤不附加人工计数。
+**人工计数**（`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`。
 

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

@@ -112,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.
 
@@ -184,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

@@ -111,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**，等待回答。下一次触发回到本步骤。
 
@@ -183,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/code-task/SKILL.en.md

@@ -13,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

@@ -13,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/complete-task/SKILL.en.md

@@ -130,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`

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

@@ -129,6 +129,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - `status`：completed
 - `current_step`：completed
 - `completed_at`：{当前时间戳}
+- `target_date`：仅当为空时写入 `completed_at` 的日期部分（`YYYY-MM-DD`）；已有值（人工填写）则保留
 - `updated_at`：{当前时间戳}
 - `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
 - 新增或更新 `## 状态核对` 段，粘贴第 0 步审计命令原文（含 `$ ` 前缀行），放在 `## 活动日志` 之前

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

@@ -15,7 +15,8 @@
         "completed_at"
       ],
       "expected_status": "completed",
-      "require_completed_at": true
+      "require_completed_at": true,
+      "require_target_date": true
     },
     "activity-log": {
       "expected_action_pattern": "(Complete Task|Completed)",

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

@@ -15,7 +15,8 @@
         "completed_at"
       ],
       "expected_status": "completed",
-      "require_completed_at": true
+      "require_completed_at": true,
+      "require_target_date": true
     },
     "activity-log": {
       "expected_action_pattern": "(Complete Task|Completed)",

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

@@ -94,7 +94,6 @@ status: active
 created_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 updated_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 agent_infra_version: {agent_infra_version}
-created_by: human
 priority:                  # required; inferred by the AI from the title/description; Urgent | High | Medium | Low
 effort:                    # required; inferred by the AI from the title/description; High | Medium | Low
 start_date:                # optional; YYYY-MM-DD
@@ -103,8 +102,7 @@ current_step: requirement-analysis
 assigned_to: {current AI agent}
 ```
 
-Note: `created_by` is `human` because the task comes from the user's description.
-priority / effort are required: the AI infers them from the task title and description (candidates in `.agents/rules/issue-fields.md`; normalize localized input). Leave start_date / target_date empty at creation - analyze-task / plan-task fill them later; do not invent dates.
+priority / effort are required: the AI infers them from the task title and description (candidates in `.agents/rules/issue-fields.md`; normalize localized input). Leave start_date / target_date empty at creation: `start_date` is written by the analyze stage and `target_date` by the complete stage; do not invent dates.
 
 ### 3. Update Task Status
 

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

@@ -93,7 +93,6 @@ status: active
 created_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 updated_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 agent_infra_version: {agent_infra_version}
-created_by: human
 priority:                  # 必填；由 AI 从标题/描述推断；Urgent | High | Medium | Low
 effort:                    # 必填；由 AI 从标题/描述推断；High | Medium | Low
 start_date:                # 可选；YYYY-MM-DD
@@ -102,8 +101,7 @@ current_step: requirement-analysis
 assigned_to: {当前 AI 代理}
 ```
 
-注意：`created_by` 为 `human`，因为任务来源于用户的描述。
-priority / effort 必填：由 AI 从任务标题与描述推断后填入（候选值见 `.agents/rules/issue-fields.md`；中文输入按本地化映射规范化）。start_date / target_date 创建时保持留空，由 analyze-task / plan-task 阶段填入；不要臆测日期。
+priority / effort 必填：由 AI 从任务标题与描述推断后填入（候选值见 `.agents/rules/issue-fields.md`；中文输入按本地化映射规范化）。start_date / target_date 创建时保持留空：`start_date` 由 analyze 阶段写入、`target_date` 由 complete 阶段写入；不要臆测日期。
 
 ### 3. 更新任务状态
 

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

@@ -54,9 +54,6 @@ Task metadata:
 ```yaml
 id: TASK-{yyyyMMdd-HHmmss}
 codescan_alert_number: <alert-number>
-severity: <critical/high/medium/low>
-rule_id: <rule-id>
-tool: <tool-name>
 ```
 
 ### 3. Update Task Status

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

@@ -54,9 +54,6 @@ description: >
 ```yaml
 id: TASK-{yyyyMMdd-HHmmss}
 codescan_alert_number: <alert-number>
-severity: <critical/high/medium/low>
-rule_id: <rule-id>
-tool: <tool-name>
 ```
 
 ### 3. 更新任务状态

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

@@ -55,7 +55,6 @@ Task metadata must include:
 ```yaml
 id: TASK-{yyyyMMdd-HHmmss}
 security_alert_number: <alert-number>
-severity: <critical/high/medium/low>
 cve_id: <CVE-ID>
 ghsa_id: <GHSA-ID>
 ```

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

@@ -55,7 +55,6 @@ description: >
 ```yaml
 id: TASK-{yyyyMMdd-HHmmss}
 security_alert_number: <alert-number>
-severity: <critical/high/medium/low>
 cve_id: <CVE-ID>
 ghsa_id: <GHSA-ID>
 ```

package/templates/.agents/skills/import-issue/SKILL.en.md

@@ -93,7 +93,7 @@ date +%Y%m%d-%H%M%S
 
 - Create the directory: `.agents/workspace/active/{task-id}/`
 - Use the `.agents/templates/task.md` template to create `task.md`
-- For Scenario C, prefer `type`, `workflow`, `branch`, `created_by`, and `milestone` from the remote frontmatter; infer missing or damaged fields from Issue labels and current rules
+- For Scenario C, prefer `type`, `workflow`, `branch`, and `milestone` from the remote frontmatter; infer missing or damaged fields from Issue labels and current rules
 - Always write `current_step` as `requirement-analysis`; do not restore the remote original `current_step`
 
 Task metadata:
@@ -107,7 +107,6 @@ status: active
 created_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 updated_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 agent_infra_version: {agent_infra_version}
-created_by: human
 priority:                  # optional; preserve source/frontmatter value when available
 effort:                    # optional; preserve source/frontmatter value when available
 start_date:                # optional; preserve explicit YYYY-MM-DD when available

package/templates/.agents/skills/import-issue/SKILL.zh-CN.md

@@ -93,7 +93,7 @@ date +%Y%m%d-%H%M%S
 
 - 创建目录：`.agents/workspace/active/{task-id}/`
 - 使用 `.agents/templates/task.md` 模板创建 `task.md`
-- 场景 C 优先沿用远端 frontmatter 中的 `type`、`workflow`、`branch`、`created_by`、`milestone`；缺失或损坏字段按 Issue 标签和当前规则重新推断
+- 场景 C 优先沿用远端 frontmatter 中的 `type`、`workflow`、`branch`、`milestone`；缺失或损坏字段按 Issue 标签和当前规则重新推断
 - `current_step` 始终写入 `requirement-analysis`，不要恢复为远端原 `current_step`
 
 任务元数据：
@@ -107,7 +107,6 @@ status: active
 created_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 updated_at: {YYYY-MM-DD HH:mm:ss±HH:MM}
 agent_infra_version: {agent_infra_version}
-created_by: human
 priority:                  # 可选；有来源/frontmatter 值时保留
 effort:                    # 可选；有来源/frontmatter 值时保留
 start_date:                # 可选；有明确 YYYY-MM-DD 时保留

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

@@ -99,7 +99,7 @@ Follow the `technical-design` step in `.agents/workflows/feature-development.yam
 - [ ] Define the verification strategy (tests, manual checks)
 - [ ] Assess impact and risks
 
-When this round introduces a new key design decision, record it under `## Open Questions` according to `.agents/rules/no-mid-flow-questions.md` and write the matching `HD-` ledger row.
+When this round introduces a new key design decision, per `.agents/rules/no-mid-flow-questions.md` write its detail block (background/options/impact/recommendation) into the plan artifact'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 (evidence pointing to `{plan-artifact}#HD-N`); ordinary open questions still go under `## Open Questions`.
 
 **Design principles**:
 1. **Architectural soundness**: choose the structurally correct approach; diff size is not the primary criterion. Do not pile changes onto an unsound structure just to keep the diff small
@@ -125,7 +125,6 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - `assigned_to`: {current AI agent}
 - `updated_at`: {current time}
 - `agent_infra_version`: value from `.agents/rules/version-stamp.md`
-- If `target_date` is empty, write an estimated completion date based on the effort estimate (`YYYY-MM-DD`); leave it empty without blocking when no reasonable estimate exists; keep any existing value
 - Record the plan artifact for this round: `{plan-artifact}` (Round `{plan-round}`)
 - If the task template contains a `## Design` section, update it to link to `{plan-artifact}`
 - Mark technical-design as complete in workflow progress and include the actual round when the task template supports it