@fitlab-ai/agent-infra 0.7.7 → 0.8.1

package/templates/.agents/rules/pr-sync.github.en.md

@@ -34,7 +34,7 @@ Aggregation rules:
 - if one artifact class is missing, treat it as "no data for this stage" and continue
 - Manual verification section: include only post-code-stage checks that still require a human to execute or judge and that the AI cannot close on its own.
   - **Admission boundary**: the verification result depends on a real environment, permissions, account, external system, or human judgment, and cannot be closed by an agent rerunning tests, adding checks, or continuing the fix loop.
-  - **Sources**: `review-code*` "Environment-Blocked Findings", plus `code*` items that satisfy the boundary above.
+  - **Sources**: `review-code*` "Manual Validation Items", plus `code*` items that satisfy the boundary above.
   - **Wording**: each retained item must state at least "what to verify + location (file/change/scope) + why only a human can verify it".
   - **Empty rendering**: when there are no retained items, do NOT use the ⚠️ alarm style (it falsely implies a problem). Render the whole block as: heading `### ✅ No Manual Verification Needed` and a single line `No items in this change require manual confirmation.`, with no item list. Only use the `### ⚠️ Manual Verification Required` heading + item list when retained items exist.
 
@@ -51,7 +51,7 @@ Use this canonical comment body template:
 
 **Updated At**: {current-time}
 
-{manual-verify-section}
+{manual-validation-section}
 
 ### Key Technical Decisions
 
@@ -72,7 +72,7 @@ Use this canonical comment body template:
 *Generated by {agent} · Internal tracking: {task-id}*
 ```
 
-> Render `{manual-verify-section}` per the "manual verification section" aggregation rule above: with retained items → `### ⚠️ Manual Verification Required` heading + quote + item list; with none → `### ✅ No Manual Verification Needed` heading + a single line `No items in this change require manual confirmation.` (no ⚠️, no list).
+> Render `{manual-validation-section}` per the "manual verification section" aggregation rule above: with retained items → `### ⚠️ Manual Verification Required` heading + quote + item list; with none → `### ✅ No Manual Verification Needed` heading + a single line `No items in this change require manual confirmation.` (no ⚠️, no list).
 
 ## Comment Lookup And Update
 

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

@@ -34,7 +34,7 @@
 - 某一类产物缺失时，按“无该阶段数据”处理并继续生成
 - 需人工校验段落：只收进入 code 阶段后仍需人实际执行或判断、AI 无法自行关闭的校验点。
   - **准入边界**：校验结论依赖真实环境、权限、账号、外部系统或人工判断，且无法通过 agent 重跑测试、补充检查或继续修复自行关闭。
-  - **来源**：`review-code*` 的「环境性遗留」，以及 `code*` 中满足上述边界的校验点。
+  - **来源**：`review-code*` 的「人工校验项」，以及 `code*` 中满足上述边界的校验点。
   - **写法**：每条保留项至少写明「校验什么 + 定位（文件/改动/范围）+ 为什么只能由人校验」。
   - **空集渲染**：无保留项时，不要使用 ⚠️ 告警样式（会让人误以为有问题）。整段降级渲染为：标题 `### ✅ 无需人工校验`，正文一行 `本次改动无需人工确认事项。`，不带条目列表。有保留项时才用 `### ⚠️ 需人工校验` 标题 + 条目列表。
 
@@ -51,7 +51,7 @@
 
 **更新时间**：{当前时间}
 
-{manual-verify-section}
+{manual-validation-section}
 
 ### 关键技术决策
 
@@ -72,7 +72,7 @@
 *由 {agent} 自动生成 · 内部追踪：{task-id}*
 ```
 
-> `{manual-verify-section}` 按上文「需人工校验段落」聚合规则渲染：有保留项 → `### ⚠️ 需人工校验` 标题 + 引用说明 + 条目列表；无保留项 → `### ✅ 无需人工校验` 标题 + 一行 `本次改动无需人工确认事项。`（不带 ⚠️、不带列表）。
+> `{manual-validation-section}` 按上文「需人工校验段落」聚合规则渲染：有保留项 → `### ⚠️ 需人工校验` 标题 + 引用说明 + 条目列表；无保留项 → `### ✅ 无需人工校验` 标题 + 一行 `本次改动无需人工确认事项。`（不带 ⚠️、不带列表）。
 
 ## 评论查找与更新
 

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-validation: {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-validation` (`{e}`) parses the `Manual-validation: {n}` source field from the review done note (normalized to the same field when displayed), 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-validation: {e}, Human-decision: {h}`。`Human-decision`（`{h}`）按 canonical 步骤名前缀（`Review Analysis` / `Review Plan` / `Review Code`）映射到 `analysis` / `plan` / `code`，统计 `## 审查分歧账本` 中对应阶段 `status ∈ {needs-human-decision, human-decided}` 的当前累计数量；`Manual-validation`（`{e}`）解析 review done note 中的 `Manual-validation: {n}` 源字段（展示时归一化为同一字段），缺失为 `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

@@ -12,8 +12,8 @@ Implement the approved plan and produce `code.md` or `code-r{N}.md`. This skill
 ## Boundary / Critical Rules
 
 - 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
+- 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; manual-validation items are out of scope
+- 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

@@ -12,8 +12,8 @@ description: >
 ## 行为边界 / 关键规则
 
 - 严格遵循最新方案产物：`plan.md` 或 `plan-r{N}.md`
-- 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；env-blocked 项不在修复范围
-- 实现中遇到方案未覆盖的关键设计决策时，按 `.agents/rules/no-mid-flow-questions.md` 判据记录 `[needs-human-decision]` / `HD-` 行，不中途提问或擅自扩范围
+- 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；manual-validation 项不在修复范围
+- 实现中遇到方案未覆盖的关键设计决策时，按 `.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
@@ -168,7 +168,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 记录 Round `{code-round}` 的 `{code-artifact}`
 - 追加：
   - 初次实现：`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Task (Round {N})** by {agent} — Code implemented, {n} files modified, {n} tests passed → {code-artifact}`
-  - 修复模式：`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Task (Round {N}, fix for {review-artifact})** by {agent} — Fixed {n} blockers, {n} major, {n} minor issues[, skipped {n} env-blocked] → {code-artifact}`
+  - 修复模式：`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Task (Round {N}, fix for {review-artifact})** by {agent} — Fixed {n} blockers, {n} major, {n} minor issues[, skipped {n} manual-validation] → {code-artifact}`
 
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续；执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测）：
 - 按 issue-sync.md 设置 `status: in-progress`

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

@@ -46,7 +46,7 @@ Verdict mapping:
 - `需要修改` / `Changes Requested` -> `Changes Requested`
 - `拒绝` / `Rejected` -> `Rejected`
 
-env-blocked counts do not affect mode selection.
+manual-validation counts do not affect mode selection.
 
 ## Output Contract
 

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

@@ -46,7 +46,7 @@ node .agents/skills/code-task/scripts/detect-mode.js .agents/workspace/active/{t
 - `需要修改` / `Changes Requested` -> `Changes Requested`
 - `拒绝` / `Rejected` -> `Rejected`
 
-env-blocked 计数不参与 mode 判定。
+manual-validation 计数不参与 mode 判定。
 
 ## 输出契约
 

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

@@ -27,9 +27,9 @@ Detailed priority rules:
 - Minor issues are optional only after Blockers and Majors are resolved
 - If you disagree with a finding, or judge it hallucinated after verification, do not silently skip it; give a counter-argument in the report's `## Per-Finding Verification` section and record it under unresolved issues
 
-### Meta-category: env-blocked
+### Meta-category: manual-validation
 
-env-blocked findings are outside the repair scope. Handling rules:
+manual-validation findings are outside the repair scope. Handling rules:
 - do not write code changes for these findings
 - list them unchanged in the code report's "Environment-Blocked Handling" section and mark them "outside AI repair scope"
 - do not repeat them under unresolved issues, to avoid visually double-counting them
@@ -66,7 +66,7 @@ Fix status:
 - Blockers fixed: {fixed-blockers}/{total-blockers}
 - Major issues fixed: {fixed-majors}/{total-majors}
 - Minor issues fixed: {fixed-minors}/{total-minors}
-- [If env-blocked > 0] env-blocked skipped: {count}
+- [If manual-validation > 0] manual-validation skipped: {count}
 - All tests passing: {yes/no}
 - Review input: {review-artifact}
 - Code artifact: {code-artifact}

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

@@ -27,11 +27,11 @@
 - 只有在 Blocker 和 Major 都解决后，Minor 才是可选项
 - 如果你不同意某条审查意见，或核实后判定为幻觉，不要静默跳过，而是在报告 `## 对审查发现的逐条核实` 给出反证并记录到 unresolved issues
 
-### 元类目：env-blocked
+### 元类目：manual-validation
 
-env-blocked 项不在修复范围。处理规则：
+manual-validation 项不在修复范围。处理规则：
 - 不要为这些项编写代码改动
-- 在 code 报告的「环境性遗留处理」段落原样列出，标注「不在 AI 修复范围」
+- 在 code 报告的「人工校验项处理」段落原样列出，标注「不在 AI 修复范围」
 - 不要在 unresolved 段落里重复列出（避免视觉计数翻倍）
 - 这些项的去向：维护者在 PR description 中以「待人工验证」清单承接
 
@@ -66,7 +66,7 @@ env-blocked 项不在修复范围。处理规则：
 - 阻塞项修复：{数量}/{总数}
 - 主要问题修复：{数量}/{总数}
 - 次要问题修复：{数量}/{总数}
-- [如 env-blocked > 0] 环境性遗留跳过：{数量}
+- [如 manual-validation > 0] 人工校验项跳过：{数量}
 - 所有测试通过：{是/否}
 - 审查输入：{review-artifact}
 - 修复产物：{code-artifact}

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-pr/reference/comment-publish.en.md

@@ -9,7 +9,7 @@ Read this file before creating or updating the single reviewer-facing PR summary
 - Generate or update the `<!-- sync-pr:{task-id}:summary -->` comment with the canonical template from `.agents/rules/pr-sync.md`
 - When a matching summary comment already exists, PATCH only when the body changed; otherwise skip the write
 - In this skill, summary sync failures follow the existing `create-pr` error handling and must not roll back an already-created PR
-- Populate `{manual-verify-section}` per the aggregation rules in `.agents/rules/pr-sync.md`: include only post-code-stage checks that the AI cannot close on its own and that require a human to execute or judge; sources are `review-code*` "Environment-Blocked Findings" plus `code*` items that satisfy the admission boundary; each item must state "what to verify + location + why only a human can verify it". Render in two branches: **with retained items** → `### ⚠️ Manual Verification Required` heading + item list; **with none** → `### ✅ No Manual Verification Needed` heading + a single line (no ⚠️, no old list placeholder)
+- Populate `{manual-validation-section}` per the aggregation rules in `.agents/rules/pr-sync.md`: include only post-code-stage checks that the AI cannot close on its own and that require a human to execute or judge; sources are `review-code*` "Manual Validation Items" plus `code*` items that satisfy the admission boundary; each item must state "what to verify + location + why only a human can verify it". Render in two branches: **with retained items** → `### ⚠️ Manual Verification Required` heading + item list; **with none** → `### ✅ No Manual Verification Needed` heading + a single line (no ⚠️, no old list placeholder)
 
 ## Result Reporting
 

package/templates/.agents/skills/create-pr/reference/comment-publish.zh-CN.md

@@ -9,7 +9,7 @@
 - 按 `.agents/rules/pr-sync.md` 中的唯一权威模板生成或更新 `<!-- sync-pr:{task-id}:summary -->` 评论
 - PR 已存在同标记评论时，只在正文变化时 PATCH；否则跳过写入
 - 本 skill 中，摘要同步失败沿用 `create-pr` 的现有错误处理，不回滚已经创建的 PR
-- 按 `.agents/rules/pr-sync.md` 的聚合规则填充 `{manual-verify-section}`：只收进入 code 阶段后 AI 无法自行关闭、需要人实际执行或判断的校验点；来源为 `review-code*` 的「环境性遗留」以及 `code*` 中满足准入边界的校验点；每条写明「校验什么 + 定位 + 为什么只能由人校验」。按两分支渲染：**有保留项** → `### ⚠️ 需人工校验` 标题 + 条目列表；**无保留项** → `### ✅ 无需人工校验` 标题 + 单行说明（不带 ⚠️、不写旧的列表占位）
+- 按 `.agents/rules/pr-sync.md` 的聚合规则填充 `{manual-validation-section}`：只收进入 code 阶段后 AI 无法自行关闭、需要人实际执行或判断的校验点；来源为 `review-code*` 的「人工校验项」以及 `code*` 中满足准入边界的校验点；每条写明「校验什么 + 定位 + 为什么只能由人校验」。按两分支渲染：**有保留项** → `### ⚠️ 需人工校验` 标题 + 条目列表；**无保留项** → `### ✅ 无需人工校验` 标题 + 单行说明（不带 ⚠️、不写旧的列表占位）
 
 ## 结果回传
 

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 时保留