@fitlab-ai/agent-infra 0.7.5 → 0.7.7

package/lib/task/commands/log.ts

@@ -4,16 +4,23 @@ import { resolveTaskRef } from '../resolve-ref.ts';
 
 const USAGE = `Usage: ai task log <N | #N | TASK-id>
 
-Renders a task's activity log as a chronological timeline table.
+Renders a task's activity log as a per-step status table. A step's start and
+completion are paired onto one row: STARTED holds the start time, DONE the
+completion time (or '(in progress)' while still running).
   <ref>   Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
-Columns: # (timeline position) / TIME / STEP / AGENT / NOTE
+Columns: # (row) / STEP / AGENT / STARTED / DONE / NOTE
+  A human-executed step shows AGENT as 'human' and, when it has no start marker,
+  a '-' STARTED placeholder. Review-step NOTE also carries two human counts in
+  the verdict list, right after blockers/major/minor: manual-verify (env-blocked)
+  and human-decision (current ledger stage total).
 `;
 
-const TABLE_HEADERS = ['#', 'TIME', 'STEP', 'AGENT', 'NOTE'] as const;
+const TABLE_HEADERS = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'] as const;
 
 // The activity-log H2 heading is language-dependent (zh template / en template).
 const HEADING_RE = /^##\s+(活动日志|Activity Log)\s*$/;
+const LEDGER_HEADING_RE = /^##\s+(审查分歧账本|Review Disagreement Ledger)\s*$/;
 const NEXT_H2_RE = /^##\s/;
 // `- {time} — **{step}** by {agent} — {note}` ; the separator is an em-dash
 // (U+2014). STEP/AGENT are non-greedy so a note that itself contains ' — ' or
@@ -22,6 +29,34 @@ const ENTRY_RE =
   /^- (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}) — \*\*(.+?)\*\* by (.+?) — (.*)$/;
 
 type LogEntry = { time: string; step: string; agent: string; note: string };
+type ReviewStage = 'analysis' | 'plan' | 'code';
+type LedgerRow = { stage: string; status: string };
+
+// One rendered row = one step instance. `started`/`done` are timestamps; an empty
+// `done` with a non-empty `started` means the step is still in flight, while an
+// empty `started` is a historical done-only entry (no start marker was written).
+type StepRow = { step: string; agent: string; started: string; done: string; note: string };
+
+// A start marker reuses the normal entry grammar and only suffixes its action
+// with ` [started]`; the matching done entry carries the identical base action
+// without the suffix. Pairing therefore keys on the base action (including any
+// `(Round N)`), so every round and every repeated execution pairs on its own.
+const STARTED_SUFFIX_RE = /\s*\[started\]\s*$/;
+// Short agent tokens that actually appear in activity logs for AI executors
+// (workflow recommended_agents claude/codex/gemini/cursor + enabled TUI opencode;
+// note these differ from the `.airc.json` long names claude-code/gemini-cli).
+// Any other executor token (a human name, possibly CJK) is treated as human.
+const KNOWN_AI_AGENTS = new Set(['claude', 'codex', 'gemini', 'opencode', 'cursor']);
+const HUMAN_DECISION_STATUSES = new Set(['needs-human-decision', 'human-decided']);
+const ENV_BLOCKED_RE = /\(\+\s*(\d+)\s+env-blocked\)/i;
+// Same match plus any leading whitespace, so folding the count into the verdict
+// text drops the redundant `(+ n env-blocked)` fragment without leaving a gap.
+const ENV_BLOCKED_STRIP_RE = /\s*\(\+\s*\d+\s+env-blocked\)/i;
+const REVIEW_STAGE_PREFIXES: { prefix: string; stage: ReviewStage }[] = [
+  { prefix: 'Review Analysis', stage: 'analysis' },
+  { prefix: 'Review Plan', stage: 'plan' },
+  { prefix: 'Review Code', stage: 'code' }
+];
 
 function parseActivityLog(content: string): { sectionFound: boolean; entries: LogEntry[] } {
   const lines = content.split('\n');
@@ -44,6 +79,100 @@ function parseActivityLog(content: string): { sectionFound: boolean; entries: Lo
   return { sectionFound: true, entries: parsed.map((p) => p.entry) };
 }
 
+// Collapse a chronological entry list into per-step rows: a `[started]` marker
+// opens a row, the next matching done entry fills it in place (FIFO per base
+// action). Started-only rows stay in flight; done-only entries (legacy logs with
+// no start marker) render as standalone rows. Result order = first-seen order,
+// which is already ascending because `entries` is sorted ascending.
+function pairEntries(entries: LogEntry[]): StepRow[] {
+  const rows: StepRow[] = [];
+  const open = new Map<string, StepRow[]>();
+  for (const e of entries) {
+    const isStarted = STARTED_SUFFIX_RE.test(e.step);
+    const base = e.step.replace(STARTED_SUFFIX_RE, '');
+    if (isStarted) {
+      const row: StepRow = { step: base, agent: e.agent, started: e.time, done: '', note: e.note };
+      rows.push(row);
+      const queue = open.get(base);
+      if (queue) queue.push(row);
+      else open.set(base, [row]);
+    } else {
+      const pending = open.get(base)?.shift();
+      if (pending) {
+        // Done fills the open row; the done entry carries the meaningful note.
+        pending.done = e.time;
+        pending.agent = e.agent;
+        pending.note = e.note;
+      } else {
+        rows.push({ step: base, agent: e.agent, started: '', done: e.time, note: e.note });
+      }
+    }
+  }
+  return rows;
+}
+
+function parseReviewLedger(content: string): LedgerRow[] {
+  const lines = content.split('\n');
+  let i = 0;
+  while (i < lines.length && !LEDGER_HEADING_RE.test(lines[i]!)) i += 1;
+  if (i >= lines.length) return [];
+
+  const rows: LedgerRow[] = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (NEXT_H2_RE.test(lines[j]!)) break;
+    const line = lines[j]!.trim();
+    if (!line.startsWith('|')) continue;
+    const cells = line
+      .split('|')
+      .slice(1, -1)
+      .map((cell) => cell.trim());
+    if (cells.length < 6 || cells[0] === 'id' || /^-+$/.test(cells[0] ?? '')) continue;
+    rows.push({ stage: cells[1]!, status: cells[4]! });
+  }
+  return rows;
+}
+
+function countHumanDecisionsByStage(rows: LedgerRow[]): Map<ReviewStage, number> {
+  const counts = new Map<ReviewStage, number>();
+  for (const row of rows) {
+    if (!isReviewStage(row.stage) || !HUMAN_DECISION_STATUSES.has(row.status)) continue;
+    counts.set(row.stage, (counts.get(row.stage) ?? 0) + 1);
+  }
+  return counts;
+}
+
+function isReviewStage(stage: string): stage is ReviewStage {
+  return stage === 'analysis' || stage === 'plan' || stage === 'code';
+}
+
+function reviewStageForStep(step: string): ReviewStage | undefined {
+  return REVIEW_STAGE_PREFIXES.find(({ prefix }) => step.startsWith(prefix))?.stage;
+}
+
+function humanValidationCount(note: string): number {
+  const match = ENV_BLOCKED_RE.exec(note);
+  return match ? Number(match[1]) : 0;
+}
+
+// A step is human-executed when its agent token is not a known AI token. Take
+// the first whitespace-delimited token and drop any trailing parenthetical
+// annotation (e.g. `张三 (executed on host)` -> `张三`) before the lookup.
+function isHumanAgent(agent: string): boolean {
+  const token = agent.trim().split(/\s+/)[0]?.replace(/\(.*$/, '') ?? '';
+  return token !== '' && !KNOWN_AI_AGENTS.has(token);
+}
+
+// Fold the two human counts into a review row's verdict NOTE: comma-joined, right
+// after the blockers/major/minor list and before the ` → artifact` link, mirroring
+// the review count line. The raw `(+ n env-blocked)` fragment is dropped so the
+// env-blocked number is not shown twice (it becomes the manual-verify count).
+function foldHumanCounts(note: string, decisions: number, envBlocked: number): string {
+  const base = note.replace(ENV_BLOCKED_STRIP_RE, '');
+  const group = `Manual-verify: ${envBlocked}, Human-decision: ${decisions}`;
+  const arrow = base.indexOf(' → ');
+  return arrow === -1 ? `${base}, ${group}` : `${base.slice(0, arrow)}, ${group}${base.slice(arrow)}`;
+}
+
 function log(args: string[] = []): void {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(USAGE);
@@ -70,11 +199,22 @@ function log(args: string[] = []): void {
     process.exitCode = 1;
     return;
   }
-  const rows = entries.map((e, idx) => [String(idx + 1), e.time, e.step, e.agent, e.note]);
+  const steps = pairEntries(entries);
+  const humanDecisionCounts = countHumanDecisionsByStage(parseReviewLedger(content));
+  const rows = steps.map((s, idx) => {
+    const stage = reviewStageForStep(s.step);
+    const note = stage
+      ? foldHumanCounts(s.note, humanDecisionCounts.get(stage) ?? 0, humanValidationCount(s.note))
+      : s.note;
+    const human = isHumanAgent(s.agent);
+    const agent = human ? 'human' : s.agent;
+    const started = s.started || (human ? '-' : '');
+    return [String(idx + 1), s.step, agent, started, s.done || (s.started ? '(in progress)' : ''), note];
+  });
   for (const line of formatTable(TABLE_HEADERS, rows, { zebra: Boolean(process.stdout.isTTY) })) {
     process.stdout.write(`${line}\n`);
   }
-  process.stdout.write(`Total: ${entries.length} entries\n`);
+  process.stdout.write(`Total: ${steps.length} steps\n`);
 }
 
-export { log, parseActivityLog };
+export { log, parseActivityLog, pairEntries, isHumanAgent };

package/lib/task/index.ts

@@ -4,6 +4,7 @@ Commands:
   cat <ref> <artifact | N>               Print a task artifact (by name or number)
   files <ref>                            List artifacts in a task dir (numbered)
   grep <pattern> [ref] [artifact | N]    Literal search across task artifacts (omit ref to scan all)
+  issue-body <ref> [--template <path>]   Print a deterministic Issue body from task.md (描述 + 需求, or an Issue Form)
   log <ref>                              Render a task's activity log as a timeline
   ls [--all | --blocked | --completed]   List tasks (default: active)
   show <N | #N | TASK-id>                Print a task.md
@@ -15,6 +16,8 @@ Examples:
   ai task files 11
   ai task grep resolveArtifact
   ai task grep resolveArtifact 11
+  ai task issue-body 11
+  ai task issue-body 11 --template .github/ISSUE_TEMPLATE/05_other.yml
   ai task log 11
   ai task ls
   ai task show 11
@@ -53,6 +56,11 @@ export async function runTask(args: string[]): Promise<void> {
       grep(rest);
       break;
     }
+    case 'issue-body': {
+      const { issueBody } = await import('./commands/issue-body.ts');
+      issueBody(rest);
+      break;
+    }
     case 'log': {
       const { log } = await import('./commands/log.ts');
       log(rest);

package/lib/task/issue-form.ts

@@ -0,0 +1,77 @@
+import { parse } from 'yaml';
+
+type TaskFields = {
+  title: string;
+  description: string;
+  requirements: string;
+};
+
+// Field id -> task value mapping (single source of truth, per HD-1).
+// Only ids that map cleanly to title / description / requirements get a value;
+// every other text field gets `N/A`. This deliberately tightens the older
+// "suggested" mapping table (impact / context / alternatives / steps / expected
+// no longer flow into requirements) so the requirements checklist is never
+// pushed into an unrelated field.
+const TITLE_IDS = new Set(['summary', 'title']);
+const DESCRIPTION_IDS = new Set([
+  'description',
+  'problem',
+  'what-happened',
+  'question',
+  'current-content',
+  'issue-description',
+  'detailed-description'
+]);
+const REQUIREMENTS_IDS = new Set(['requirements', 'solution', 'suggested-content']);
+
+// Only free-text field types carry task content; structural / static fields are skipped.
+const TEXT_FIELD_TYPES = new Set(['input', 'textarea']);
+const PLACEHOLDER = 'N/A';
+
+function mapFieldValue(id: string, fields: TaskFields): string {
+  if (TITLE_IDS.has(id)) return fields.title;
+  if (DESCRIPTION_IDS.has(id)) return fields.description;
+  if (REQUIREMENTS_IDS.has(id)) return fields.requirements;
+  return '';
+}
+
+type IssueFormField = {
+  type?: unknown;
+  id?: unknown;
+  attributes?: { label?: unknown };
+};
+
+/**
+ * Render the final Issue body for a GitHub Issue Form (scenario A).
+ *
+ * Walks the form's `body[]` in order, skips `markdown` / `dropdown` /
+ * `checkboxes`, and renders each `input` / `textarea` as `### {label}` followed
+ * by the deterministically-mapped task value (or `N/A` when the field has no
+ * reliable source). The template structure is preserved; the whole task.md and
+ * its scaffolding sections are never emitted.
+ *
+ * Throws on unreadable / non-object YAML or a missing `body[]` list so the
+ * caller can fall back to the default body.
+ */
+function renderTemplateBody(formText: string, fields: TaskFields): string {
+  const doc = parse(formText) as { body?: unknown } | null;
+  if (!doc || typeof doc !== 'object' || !Array.isArray(doc.body)) {
+    throw new Error('Issue Form has no body[] list');
+  }
+  const sections: string[] = [];
+  for (const raw of doc.body as IssueFormField[]) {
+    if (!raw || typeof raw !== 'object') continue;
+    const type = typeof raw.type === 'string' ? raw.type : '';
+    if (!TEXT_FIELD_TYPES.has(type)) continue;
+    const label = typeof raw.attributes?.label === 'string' ? raw.attributes.label.trim() : '';
+    if (!label) continue;
+    const id = typeof raw.id === 'string' ? raw.id : '';
+    const mapped = mapFieldValue(id, fields);
+    const value = mapped.trim() === '' ? PLACEHOLDER : mapped;
+    sections.push(`### ${label}\n\n${value}`);
+  }
+  return `${sections.join('\n\n')}\n`;
+}
+
+export { renderTemplateBody, mapFieldValue, PLACEHOLDER };
+export type { TaskFields };

package/lib/task/sections.ts

@@ -0,0 +1,44 @@
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Return the body of the first `## {alias}` section (any alias matches), from
+ * the heading line to the next `## ` heading or EOF. Lines are preserved
+ * verbatim (checkbox text is never normalized); only leading/trailing blank
+ * lines are trimmed. Returns '' when no alias heading is present.
+ */
+function extractSection(content: string, aliases: string[]): string {
+  const lines = content.split('\n');
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]!.trim();
+    if (aliases.some((alias) => new RegExp(`^##\\s+${escapeRegExp(alias)}\\s*$`).test(line))) {
+      start = i + 1;
+      break;
+    }
+  }
+  if (start === -1) return '';
+  let end = lines.length;
+  for (let i = start; i < lines.length; i += 1) {
+    if (/^##\s+/.test(lines[i]!)) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+}
+
+/**
+ * Return the heading alias that actually appears as a `## {alias}` line, so a
+ * rendered section can mirror the source language. Falls back to the first
+ * alias when none is present.
+ */
+function findSectionHeading(content: string, aliases: string[]): string {
+  for (const alias of aliases) {
+    if (new RegExp(`^##\\s+${escapeRegExp(alias)}\\s*$`, 'm').test(content)) return alias;
+  }
+  return aliases[0]!;
+}
+
+export { extractSection, findSectionHeading };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -47,7 +47,8 @@
     "cross-spawn": "^7.0.6",
     "picocolors": "1.1.1",
     "semver": "^7.8.1",
-    "smol-toml": "^1.6.1"
+    "smol-toml": "^1.6.1",
+    "yaml": "^2.9.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/build.js && node scripts/build-inline.js",

package/templates/.agents/README.en.md

@@ -163,11 +163,13 @@ Recommended frontmatter:
 ```yaml
 ---
 name: enforce-style
-description: "Apply the team style guide before code review"
+description: "Apply the team style guide before code review. Use when you need to align the team's code style before review"
 args: "<task-id>"   # optional
 ---
 ```
 
+Write `description` as "one-line responsibility + scenario clause": after the short responsibility, append "Use when …" (the Chinese `SKILL.zh-CN.md` variant uses "当……时使用") as the cross-TUI trigger semantics, so Agent Skills-capable tools can self-discover the skill in natural conversation. Do **not** add a separate `triggers` (or similar) frontmatter field for this.
+
 After adding or updating a custom skill, run `update-agent-infra` again. The sync step detects non-built-in skills and generates matching commands for Claude Code, Gemini CLI, and OpenCode automatically.
 
 ### Shared skill sources

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

@@ -163,11 +163,13 @@
 ```yaml
 ---
 name: enforce-style
-description: "在代码审查前应用团队风格规范"
+description: "在代码审查前应用团队风格规范。当需要在评审前统一团队代码风格时使用"
 args: "<task-id>"   # 可选
 ---
 ```
 
+`description` 采用「一句话职责 + 场景触发子句」写法：在简短职责描述后补充「当……时使用」（英文 `SKILL.en.md` 用「Use when …」），作为跨 TUI 的触发语义，供支持 Agent Skills 的工具在自然对话中自发现该 skill。**不要**为此新增 `triggers` 等额外 frontmatter 字段。
+
 新增或修改自定义 skill 后，再执行一次 `update-agent-infra`。同步过程会自动检测非内置 skill，并为 Claude Code、Gemini CLI、OpenCode 生成对应命令。
 
 ### 共享 skill 源

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

@@ -22,11 +22,11 @@ After `create-task` writes the local `task.md`, follow this rule to cascade Issu
 
 Pull the following from `task.md`:
 
-- Task title (the first `# ` heading, stripped of `任务：` / `Task:` prefixes)
-- The `## Description` / `## 描述` section
-- The `## Requirements` / `## 需求` section
+- Task title (the first `# ` heading, stripped of `任务：` / `Task:` prefixes) — used to build the Issue title
 - frontmatter fields `type` and (optionally) `milestone`
 
+> The Issue **body** is not extracted by hand here. It is generated deterministically in §3 by the `ai task issue-body` command from the `## 描述` / `## 需求` sections; callers must not assemble it themselves.
+
 Build the Issue title:
 
 | task.md `type` | Conventional Commits type |
@@ -41,45 +41,35 @@ Scope inference: read known module names from `.agents/.airc.json`'s `labels.in`
 
 ### 3. Build the Issue Body
 
+> **Mechanization boundary (mandatory)**: the Issue body is always produced deterministically by the `ai task issue-body` command; callers only pass the command's stdout to `gh issue create` via `--body-file` and must **not** assemble, rewrite, or truncate the body themselves. The command emits only the task title / `## 描述` / `## 需求` content; every other task.md scaffolding section never enters the body.
+
 Issue Form detection: follow the "Issue Template Detection" section in `.agents/rules/issue-pr-commands.md` to scan `.github/ISSUE_TEMPLATE/*.yml` (excluding `config.yml`).
 
 #### Scenario A: A matching template was detected
 
 Pick the form whose `name` (or filename) best matches the task type (e.g., a task with `type: bugfix` prefers a form whose name contains `bug`); if no match, fall back to a generic form like `other.yml`; if none, take the first form in the directory.
 
-Populate the form by following the field-handling rules in `.agents/rules/issue-pr-commands.md` § "Issue Template Detection":
-
-- `textarea` / `input` fields: use `attributes.label` as a markdown heading and pull values from task.md
-- `markdown` fields: skip (these are description blurbs)
-- `dropdown` / `checkboxes` fields: skip
+Once the form file `{form-path}` is chosen, let the command render the final body from that Issue Form and write it to the body file `{body-file}` for §5:
 
-Recommended field-to-source mapping:
-
-| Template field hint | Source in task.md |
-|---|---|
-| `summary`, `title` | task title |
-| `description`, `problem`, `what happened`, `issue-description`, `current-content` | task description |
-| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | requirements list (preserve checked / unchecked state as-is) |
-| Other `textarea` / `input` fields | task description, or `N/A` if missing |
+```bash
+ai task issue-body {task-id} --template "{form-path}" > "{body-file}"
+```
 
-Whenever task.md does not provide a usable value, write `N/A`.
+The command skips `markdown` / `dropdown` / `checkboxes` fields and, for `input` / `textarea` fields, uses `attributes.label` as the heading and deterministically fills the task title / description / requirements by field `id`, writing `N/A` for fields with no reliable source (the field mapping table is the single source of truth inside the command and is not restated here). When the command exits non-zero (missing file / invalid YAML / no `body`), regenerate `{body-file}` with the Scenario B command instead.
 
 #### Scenario B: No template, or template parsing failed
 
-Fall back to the default body:
-
-```markdown
-## Description
+Let the command emit the default body (only `## 描述` + `## 需求`, checkbox text preserved verbatim, missing sections filled with `N/A`) into `{body-file}`:
 
-{task description, or N/A if missing}
+```bash
+ai task issue-body {task-id} > "{body-file}"
+```
 
-## Requirements
+#### Red line: never use the entire task.md as the body
 
-- [ ] {requirement-1}
-- [ ] {requirement-2}
-```
+In both Scenario A and B, the body may only come from `ai task issue-body` stdout and contains **only the description + requirements content** (Scenario A is the equivalent content mapped onto template fields).
 
-If the requirements list is empty, write `N/A` in that section.
+Wrong example (❌ forbidden): pasting the entire task.md — including scaffolding sections such as `## 分析` / `## 设计` / `## 实现备注` / `## 审查反馈` / `## 审查分歧账本` / `## 人工裁决` / `## 活动日志` / `## 完成检查清单` and `#XXX` placeholders — directly as the Issue body. Those sections only go to the `sync-issue:{task-id}:task` comment, never the body.
 
 ### 4. Resolve labels / Issue Type / milestone
 
@@ -137,17 +127,18 @@ When a milestone is selected, pass the release line (or `General Backlog` or the
 
 ### 5. Call the GitHub CLI to Create the Issue
 
-Run the "Create Issue" command from `.agents/rules/issue-pr-commands.md`:
+Run the "Create Issue" command from `.agents/rules/issue-pr-commands.md`; always use the `{body-file}` produced in §3, overriding the generic command's `--body`:
 
 ```bash
 gh issue create -R "$upstream_repo" \
   --title "{title}" \
-  --body "{body}" \
+  --body-file "{body-file}" \
   --assignee @me \
   {label-args} \
   {milestone-arg}
 ```
 
+- `{body-file}` is the body file produced in §3 by `ai task issue-body`; do **not** switch back to `--body` and assemble the body by hand
 - `{label-args}` is expanded from the result of §4 into multiple `--label "..."`; if empty, omit the entire argument
 - `{milestone-arg}` is only expanded to `--milestone "..."` when `has_triage=true` and milestone is non-empty; otherwise omit
 - `--assignee @me` requires no permission probe; on failure, skip silently

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-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,27 @@ 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 `## 审查分歧账本`)
+
+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.