@fitlab-ai/agent-infra 0.7.6 → 0.7.7

package/lib/sandbox/commands/show.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import type { SandboxConfig } from '../config.ts';
+import { loadConfig } from '../config.ts';
+import { assertValidBranchName, worktreeDirCandidates } from '../constants.ts';
+import { resolveBranchArg } from './list-running.ts';
+import { resolveTools, toolConfigDirCandidates } from '../tools.ts';
+
+const USAGE = `Usage: ai sandbox show <branch | TASK-id | N | '#N'>
+
+Shows one sandbox's worktree path and per-tool state paths (Claude Code,
+Codex, Gemini CLI, OpenCode). The argument follows the same contract as
+'ai sandbox exec' and 'ai sandbox start': N (bare) is the recommended form
+for task short ids (e.g. 'ai sandbox show 11'); '#N', a TASK-id, or a plain
+branch name are also accepted. Use 'ai sandbox ls' for the container list.`;
+
+export type SandboxDetail = {
+  worktrees: string[];
+  toolStates: { name: string; entries: string[] }[];
+};
+
+function existingDirs(candidates: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const candidate of candidates) {
+    if (!seen.has(candidate) && fs.existsSync(candidate)) {
+      seen.add(candidate);
+      result.push(candidate);
+    }
+  }
+  return result;
+}
+
+export function collectSandboxDetail(config: SandboxConfig, branch: string): SandboxDetail {
+  const worktrees = existingDirs(worktreeDirCandidates(config, branch));
+  const toolStates = resolveTools(config).map((tool) => ({
+    name: tool.name,
+    entries: existingDirs(toolConfigDirCandidates(tool, config.project, branch))
+  }));
+  return { worktrees, toolStates };
+}
+
+export function show(args: string[] = []): void {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(`${USAGE}\n`);
+    if (args.length === 0) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const config = loadConfig();
+  const branch = resolveBranchArg(args[0]!, { repoRoot: config.repoRoot });
+  assertValidBranchName(branch);
+
+  const detail = collectSandboxDetail(config, branch);
+
+  p.intro(pc.cyan(`Sandbox detail for ${config.project} · ${branch}`));
+
+  p.log.step('Worktree');
+  if (detail.worktrees.length === 0) {
+    p.log.warn('  No worktree for this branch');
+  } else {
+    for (const worktree of detail.worktrees) {
+      process.stdout.write(`  ${worktree}\n`);
+    }
+  }
+
+  for (const tool of detail.toolStates) {
+    p.log.step(`${tool.name} state`);
+    if (tool.entries.length === 0) {
+      p.log.warn(`  No ${tool.name} sandbox state`);
+      continue;
+    }
+    for (const entry of tool.entries) {
+      process.stdout.write(`  ${entry}\n`);
+    }
+  }
+}

package/lib/sandbox/index.ts

@@ -9,6 +9,8 @@ Commands:
   ls                           List sandboxes for the current project (the '#'
                                column is a display-only row number; the 'SHORT'
                                column shows the active task short id, '-' if none)
+  show <branch | TASK-id | N | '#N'>
+                               Show one sandbox's worktree and per-tool state paths
   prune [--dry-run]            Remove orphaned per-branch state dirs
   rebuild [--quiet] [--refresh]
                                Rebuild the sandbox image (--refresh pulls base + tools)
@@ -56,6 +58,11 @@ export async function runSandbox(args: string[]): Promise<void> {
       ls(rest);
       break;
     }
+    case 'show': {
+      const { show } = await import('./commands/show.ts');
+      show(rest);
+      break;
+    }
     case 'prune': {
       const { prune } = await import('./commands/prune.ts');
       await prune(rest);

package/lib/task/commands/issue-body.ts

@@ -0,0 +1,102 @@
+import fs from 'node:fs';
+import { resolveTaskRef } from '../resolve-ref.ts';
+import { extractTitle } from '../frontmatter.ts';
+import { extractSection, findSectionHeading } from '../sections.ts';
+import { renderTemplateBody, PLACEHOLDER } from '../issue-form.ts';
+import type { TaskFields } from '../issue-form.ts';
+
+const USAGE = `Usage: ai task issue-body <N | #N | TASK-id> [--template <path>]
+
+Print a deterministic Issue body extracted from a task's task.md.
+  <ref>               Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  --template <path>   Render the final body for the given GitHub Issue Form (scenario A);
+                      without it, print the default '描述 + 需求' body (scenario B).
+
+Only the task title, '## 描述' and '## 需求' sections are ever emitted; the rest of
+task.md (scaffolding sections, placeholders) is never written to the body.
+`;
+
+const DESCRIPTION_ALIASES = ['描述', 'Description'];
+const REQUIREMENTS_ALIASES = ['需求', 'Requirements'];
+
+/**
+ * Build the scenario B default body, mirroring whichever heading language the
+ * task.md actually uses, with empty sections falling back to `N/A`.
+ */
+function buildDefaultBody(content: string): string {
+  const descHeading = findSectionHeading(content, DESCRIPTION_ALIASES);
+  const reqHeading = findSectionHeading(content, REQUIREMENTS_ALIASES);
+  const description = extractSection(content, DESCRIPTION_ALIASES) || PLACEHOLDER;
+  const requirements = extractSection(content, REQUIREMENTS_ALIASES) || PLACEHOLDER;
+  return `## ${descHeading}\n\n${description}\n\n## ${reqHeading}\n\n${requirements}\n`;
+}
+
+function readTaskFields(content: string): TaskFields {
+  return {
+    title: extractTitle(content),
+    description: extractSection(content, DESCRIPTION_ALIASES),
+    requirements: extractSection(content, REQUIREMENTS_ALIASES)
+  };
+}
+
+function issueBody(args: string[] = []): void {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    if (args.length === 0) process.exitCode = 1;
+    return;
+  }
+
+  let ref: string | undefined;
+  let templatePath: string | undefined;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]!;
+    if (arg === '--template') {
+      templatePath = args[i + 1];
+      i += 1;
+    } else if (ref === undefined) {
+      ref = arg;
+    }
+  }
+
+  if (!ref) {
+    process.stderr.write('ai task issue-body: missing task ref\n');
+    process.exitCode = 1;
+    return;
+  }
+  if (templatePath === undefined && args.includes('--template')) {
+    process.stderr.write('ai task issue-body: --template requires a path\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const resolved = resolveTaskRef(ref);
+  if (!resolved.ok) {
+    process.stderr.write(`ai task issue-body: ${resolved.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+
+  if (templatePath !== undefined) {
+    let formText: string;
+    try {
+      formText = fs.readFileSync(templatePath, 'utf8');
+    } catch (e) {
+      process.stderr.write(`ai task issue-body: cannot read template '${templatePath}': ${(e as Error).message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      process.stdout.write(renderTemplateBody(formText, readTaskFields(content)));
+    } catch (e) {
+      process.stderr.write(`ai task issue-body: cannot render template '${templatePath}': ${(e as Error).message}\n`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  process.stdout.write(buildDefaultBody(content));
+}
+
+export { issueBody, buildDefaultBody };

package/lib/task/commands/log.ts

@@ -10,12 +10,17 @@ 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;
 
 // 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
@@ -24,6 +29,8 @@ 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
@@ -35,6 +42,21 @@ 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 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');
@@ -89,6 +111,68 @@ function pairEntries(entries: LogEntry[]): StepRow[] {
   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);
@@ -116,18 +200,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(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: ${steps.length} steps\n`);
 }
 
-export { log, parseActivityLog, pairEntries };
+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.6",
+  "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