@fitlab-ai/agent-infra 0.7.6 → 0.8.0

package/lib/task/commands/log.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { formatTable } from '../../table.ts';
 import { resolveTaskRef } from '../resolve-ref.ts';
+import { parseLedger, HUMAN_DECISION_STATUSES, type LedgerRow } from '../ledger.ts';
 
 const USAGE = `Usage: ai task log <N | #N | TASK-id>
 
@@ -10,6 +11,10 @@ completion time (or '(in progress)' while still running).
   <ref>   Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
 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 = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'] as const;
@@ -24,6 +29,7 @@ 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';
 
 // 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
@@ -35,6 +41,20 @@ type StepRow = { step: string; agent: string; started: string; done: string; not
 // 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 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');
@@ -89,6 +109,47 @@ function pairEntries(entries: LogEntry[]): StepRow[] {
   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);
@@ -116,18 +177,21 @@ function log(args: string[] = []): void {
     return;
   }
   const steps = pairEntries(entries);
-  const rows = steps.map((s, idx) => [
-    String(idx + 1),
-    s.step,
-    s.agent,
-    s.started,
-    s.done || (s.started ? '(in progress)' : ''),
-    s.note
-  ]);
+  const humanDecisionCounts = countHumanDecisionsByStage(parseLedger(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: ${steps.length} steps\n`);
 }
 
-export { log, parseActivityLog, pairEntries };
+export { log, parseActivityLog, pairEntries, isHumanAgent };

package/lib/task/index.ts

@@ -2,8 +2,10 @@ const USAGE = `Usage: ai task <command> [options]
 
 Commands:
   cat <ref> <artifact | N>               Print a task artifact (by name or number)
+  decisions, d <ref> [selector]          List human-decision (HD-) items, or show one's detail
   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
@@ -12,9 +14,13 @@ Commands:
 Examples:
   ai task cat 11 analysis
   ai task cat 11 3
+  ai task decisions 11
+  ai task d 11 HD-3 --format markdown
   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
@@ -43,6 +49,12 @@ export async function runTask(args: string[]): Promise<void> {
       cat(rest);
       break;
     }
+    case 'decisions':
+    case 'd': {
+      const { decisions } = await import('./commands/decisions.ts');
+      decisions(rest);
+      break;
+    }
     case 'files': {
       const { files } = await import('./commands/files.ts');
       files(rest);
@@ -53,6 +65,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/ledger.ts

@@ -0,0 +1,73 @@
+// Shared parser for the task.md `## 审查分歧账本` (Review Disagreement Ledger).
+// Single source of truth for ledger row parsing across `ai task` commands
+// (log, decisions) — see the plan's D1 constraint "no third parser". The gate
+// parser in `.agents/scripts/validate-artifact.js` is a separate concern and
+// must be kept semantically in sync by hand (noted in review-handshake.md).
+
+// The ledger H2 heading is language-dependent (zh template / en template).
+const LEDGER_HEADING_RE = /^##\s+(审查分歧账本|Review Disagreement Ledger)\s*$/;
+const NEXT_H2_RE = /^##\s/;
+
+type LedgerRow = {
+  id: string;
+  stage: string;
+  round: string;
+  severity: string;
+  status: string;
+  evidence: string;
+};
+
+// Terminal statuses the completion gates treat as resolved.
+const LEDGER_TERMINAL = new Set(['confirmed', 'closed', 'human-decided']);
+// Statuses that represent an executor-raised human-decision row (pending or done).
+const HUMAN_DECISION_STATUSES = new Set(['needs-human-decision', 'human-decided']);
+
+// Parse all rows of the disagreement ledger table. Skips the heading, the
+// header row (`| id | ... |`) and the `|---|` separator; ignores non-`|` lines.
+// Rows with fewer than 6 columns are skipped (mirrors the JS gate parser).
+function parseLedger(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) continue;
+    if (cells[0] === 'id' || /^-+$/.test(cells[0] ?? '')) continue;
+    rows.push({
+      id: cells[0]!,
+      stage: cells[1]!,
+      round: cells[2]!,
+      severity: cells[3]!,
+      status: cells[4]!,
+      evidence: cells[5]!
+    });
+  }
+  return rows;
+}
+
+// Allocate the next globally-unique human-decision id. Scans every `HD-<n>`
+// already present in the ledger (across all stages) and returns `HD-{max+1}`,
+// or `HD-1` when none exist. Global monotonic allocation prevents id collisions
+// across the analysis / plan / code stages (plan PL-2).
+function nextHdId(rows: readonly LedgerRow[]): string {
+  let max = 0;
+  for (const row of rows) {
+    const m = /^HD-(\d+)$/.exec(row.id);
+    if (!m) continue;
+    const n = Number.parseInt(m[1]!, 10);
+    if (n > max) max = n;
+  }
+  return `HD-${max + 1}`;
+}
+
+export { parseLedger, nextHdId, LEDGER_TERMINAL, HUMAN_DECISION_STATUSES };
+export type { LedgerRow };

package/lib/task/sections.ts

@@ -0,0 +1,73 @@
+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]!;
+}
+
+/**
+ * Return the body of the first `### {headingPrefix}` sub-section, from the
+ * heading line (inclusive) to the next `### ` / `## ` heading or EOF. Used to
+ * pull a single `### HD-N` human-decision detail block out of an artifact. The
+ * prefix must be followed by a word boundary so `HD-1` does not match `HD-10`
+ * (e.g. `### HD-1`, `### HD-1：标题`, `### HD-1 [needs-human-decision]`). Leading
+ * and trailing blank lines are trimmed. Returns '' when no match is present.
+ */
+function extractSubSection(content: string, headingPrefix: string): string {
+  const lines = content.split('\n');
+  const headRe = new RegExp(`^###\\s+${escapeRegExp(headingPrefix)}(?![\\w-])`);
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (headRe.test(lines[i]!.trim())) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return '';
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^###?\s+/.test(lines[i]!)) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+}
+
+export { extractSection, findSectionHeading, extractSubSection };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.7.6",
+  "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,11 +43,13 @@
     "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",
-    "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",
@@ -62,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/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