@fitlab-ai/agent-infra 0.7.7 → 0.8.1

package/lib/task/commands/status.ts

@@ -1,24 +1,27 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { commandForEngine } from '../../sandbox/shell.ts';
 import { resolveTaskRef } from '../resolve-ref.ts';
 import { enumerateArtifacts, type Artifact } from '../artifacts.ts';
 import { parseTaskFrontmatter, extractTitle, type Frontmatter } from '../frontmatter.ts';
 import { loadShortIdByTaskId } from '../short-id.ts';
+import { parseActivityLog, pairEntries } from './log.ts';
 
 const USAGE = `Usage: ai task status <N | #N | TASK-id>
 
-Prints an aggregated "health check" view for a task: header, metadata, an
-artifacts summary, git branch state, and best-effort GitHub issue/PR status.
+Prints an aggregated "health check" view for a task: header, metadata,
+artifacts, workflow/runtime execution state, and git branch state.
   <ref>   Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
-Git and Platform rows are best-effort: a failed git/gh call degrades that row to
-'-' without failing the command.
+Git rows are best-effort: a failed git call degrades that row to '-' without
+failing the command.
 `;
 
 const DASH = '-';
 
 // Subprocess boundary: the single place this command shells out. Injectable so
-// the collectors below can be unit-tested without spawning git/gh. Returns the
+// the collectors below can be unit-tested without spawning git. Returns the
 // command's stdout; throws (like execFileSync) on a non-zero exit or spawn error.
 type Runner = (file: string, args: string[]) => string;
 
@@ -27,7 +30,7 @@ function makeRunner(cwd: string): Runner {
     execFileSync(file, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
 }
 
-// Run `run` and swallow any failure into null, so a single failing git/gh call
+// Run `run` and swallow any failure into null, so a single failing git call
 // degrades only its own field instead of aborting the whole view.
 function tryRun(run: Runner, file: string, args: string[]): string | null {
   try {
@@ -47,9 +50,7 @@ const METADATA_KEYS = [
   'branch',
   'assigned_to',
   'created_at',
-  'updated_at',
-  'issue_number',
-  'pr_status'
+  'updated_at'
 ] as const;
 
 function collectMetadata(fm: Frontmatter): [string, string][] {
@@ -155,55 +156,176 @@ function collectGit(frontmatterBranch: string, run: Runner): GitInfo {
   return { current, frontmatter, match, exists, uncommitted, aheadBehind };
 }
 
-type PlatformInfo = { issue: string; pr: string };
-
-function collectPlatform(fm: Frontmatter, run: Runner): PlatformInfo {
-  let issue = DASH;
-  if (fm.issue_number && /^\d+$/.test(fm.issue_number)) {
-    const out = tryRun(run, 'gh', ['issue', 'view', fm.issue_number, '--json', 'state,labels']);
-    if (out !== null) {
-      try {
-        const data = JSON.parse(out);
-        const labels = Array.isArray(data.labels)
-          ? data.labels.map((label: { name: string }) => label.name).join(', ')
-          : '';
-        issue = labels ? `${data.state} [${labels}]` : `${data.state}`;
-      } catch {
-        issue = DASH;
-      }
-    }
+type WorkflowInfo = {
+  state: string;
+  step: string;
+  agent: string;
+  startedAt: string;
+  doneAt: string;
+  stale: string;
+};
+
+const STALE_MS = 60 * 60 * 1000;
+
+function parseActivityTime(value: string): number {
+  const epoch = Date.parse(value.replace(' ', 'T'));
+  return Number.isFinite(epoch) ? epoch : Number.NaN;
+}
+
+function collectWorkflow(content: string, now: Date = new Date()): WorkflowInfo {
+  const parsed = parseActivityLog(content);
+  if (!parsed.sectionFound || parsed.entries.length === 0) {
+    return { state: 'unknown', step: DASH, agent: DASH, startedAt: DASH, doneAt: DASH, stale: DASH };
+  }
+
+  const rows = pairEntries(parsed.entries);
+  const latest = rows.at(-1);
+  if (!latest) {
+    return { state: 'unknown', step: DASH, agent: DASH, startedAt: DASH, doneAt: DASH, stale: DASH };
   }
 
-  let pr = DASH;
-  if (fm.pr_status === 'created' && fm.pr_number && /^\d+$/.test(fm.pr_number)) {
-    const out = tryRun(run, 'gh', ['pr', 'view', fm.pr_number, '--json', 'state,statusCheckRollup']);
-    if (out !== null) {
-      try {
-        const data = JSON.parse(out);
-        const rollup = Array.isArray(data.statusCheckRollup) ? data.statusCheckRollup : [];
-        const passed = rollup.filter(
-          (check: { conclusion?: string; state?: string }) =>
-            check.conclusion === 'SUCCESS' || check.state === 'SUCCESS'
-        ).length;
-        pr = rollup.length > 0 ? `${data.state}, checks: ${passed}/${rollup.length}` : `${data.state}`;
-      } catch {
-        pr = DASH;
+  const inProgress = latest.started !== '' && latest.done === '';
+  const state = inProgress ? 'in-progress' : latest.done ? 'idle' : 'unknown';
+  let stale = DASH;
+  if (inProgress) {
+    const started = parseActivityTime(latest.started);
+    stale = Number.isFinite(started) ? (now.getTime() - started > STALE_MS ? 'yes' : 'no') : 'unknown';
+  }
+
+  return {
+    state,
+    step: latest.step || DASH,
+    agent: latest.agent || DASH,
+    startedAt: latest.started || DASH,
+    doneAt: latest.done || DASH,
+    stale
+  };
+}
+
+type RuntimeInfo = {
+  mode: string;
+  status: string;
+  run: string;
+  tmux: string;
+  startedAt: string;
+  finishedAt: string;
+  exitCode: string;
+  log: string;
+};
+
+type ManagedRunRecord = {
+  run_id: string;
+  engine: string;
+  container: string;
+  run_dir: string;
+  status_file: string;
+  log_file: string;
+};
+
+function latestRunRecord(taskDir: string): ManagedRunRecord | null {
+  const runsDir = path.join(taskDir, 'runs');
+  if (!fs.existsSync(runsDir)) return null;
+  const candidates: { path: string; mtimeMs: number }[] = [];
+  for (const entry of fs.readdirSync(runsDir)) {
+    if (!entry.endsWith('.json')) continue;
+    const filePath = path.join(runsDir, entry);
+    const stat = fs.statSync(filePath);
+    if (stat.isFile()) candidates.push({ path: filePath, mtimeMs: stat.mtimeMs });
+  }
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  for (const candidate of candidates) {
+    try {
+      const data = JSON.parse(fs.readFileSync(candidate.path, 'utf8'));
+      if (
+        typeof data?.run_id === 'string' &&
+        typeof data?.engine === 'string' &&
+        typeof data?.container === 'string' &&
+        typeof data?.run_dir === 'string'
+      ) {
+        return {
+          run_id: data.run_id,
+          engine: data.engine,
+          container: data.container,
+          run_dir: data.run_dir,
+          status_file:
+            typeof data.status_file === 'string' ? data.status_file : `${data.run_dir}/status`,
+          log_file:
+            typeof data.log_file === 'string' ? data.log_file : `${data.run_dir}/output.log`
+        };
       }
+    } catch {
+      // Ignore malformed local records and try the next newest file.
     }
   }
 
-  return { issue, pr };
+  return null;
+}
+
+function readRuntimeFile(record: ManagedRunRecord, filePath: string, run: Runner): string | null {
+  const command = commandForEngine(record.engine, 'docker', ['exec', record.container, 'cat', filePath]);
+  const output = tryRun(run, command.cmd, command.args);
+  return output === null ? null : output.trim();
+}
+
+function runtimeValue(record: ManagedRunRecord, name: string, run: Runner): string {
+  const output = readRuntimeFile(record, `${record.run_dir}/${name}`, run);
+  return output ? output : DASH;
+}
+
+function collectRuntime(taskDir: string, workflow: WorkflowInfo, run: Runner): RuntimeInfo {
+  const record = latestRunRecord(taskDir);
+  if (!record) {
+    return workflow.state === 'in-progress'
+      ? {
+          mode: 'unmanaged',
+          status: 'inferred-from-workflow',
+          run: DASH,
+          tmux: DASH,
+          startedAt: DASH,
+          finishedAt: DASH,
+          exitCode: DASH,
+          log: DASH
+        }
+      : {
+          mode: 'none',
+          status: DASH,
+          run: DASH,
+          tmux: DASH,
+          startedAt: DASH,
+          finishedAt: DASH,
+          exitCode: DASH,
+          log: DASH
+        };
+  }
+
+  const status = readRuntimeFile(record, record.status_file, run)?.trim() || 'unknown';
+  const session = runtimeValue(record, 'session', run);
+  const window = runtimeValue(record, 'window', run);
+  const pane = runtimeValue(record, 'pane', run);
+  const tmux = session !== DASH && window !== DASH && pane !== DASH ? `${session}:${window}:${pane}` : DASH;
+
+  return {
+    mode: 'managed-tmux',
+    status,
+    run: record.run_id,
+    tmux,
+    startedAt: runtimeValue(record, 'started_at', run),
+    finishedAt: runtimeValue(record, 'finished_at', run),
+    exitCode: runtimeValue(record, 'exit_code', run),
+    log: record.log_file
+  };
 }
 
 type StatusModel = {
   taskId: string;
   shortId: string;
   title: string;
-  issueNumber: string;
   metadata: [string, string][];
   artifacts: { count: number; groups: { stage: string; files: string[] }[] };
+  workflow: WorkflowInfo;
+  runtime: RuntimeInfo;
   git: GitInfo;
-  platform: PlatformInfo;
 };
 
 // Indent each label/value pair by two spaces and pad labels to a common width so
@@ -228,6 +350,34 @@ function renderStatus(model: StatusModel): string[] {
     lines.push(...renderPairs(model.artifacts.groups.map((group) => [group.stage, group.files.join(', ')])));
   }
 
+  lines.push(
+    '',
+    'Workflow',
+    ...renderPairs([
+      ['state', model.workflow.state],
+      ['step', model.workflow.step],
+      ['agent', model.workflow.agent],
+      ['started_at', model.workflow.startedAt],
+      ['done_at', model.workflow.doneAt],
+      ['stale', model.workflow.stale]
+    ])
+  );
+
+  lines.push(
+    '',
+    'Runtime',
+    ...renderPairs([
+      ['mode', model.runtime.mode],
+      ['status', model.runtime.status],
+      ['run', model.runtime.run],
+      ['tmux', model.runtime.tmux],
+      ['started_at', model.runtime.startedAt],
+      ['finished_at', model.runtime.finishedAt],
+      ['exit_code', model.runtime.exitCode],
+      ['log', model.runtime.log]
+    ])
+  );
+
   lines.push(
     '',
     'Git',
@@ -241,16 +391,6 @@ function renderStatus(model: StatusModel): string[] {
     ])
   );
 
-  const issueLabel = model.issueNumber ? `issue #${model.issueNumber}` : 'issue';
-  lines.push(
-    '',
-    'Platform',
-    ...renderPairs([
-      [issueLabel, model.platform.issue],
-      ['pr', model.platform.pr]
-    ])
-  );
-
   return lines;
 }
 
@@ -272,16 +412,17 @@ function status(args: string[] = []): void {
   const fm = parseTaskFrontmatter(content);
   const run = makeRunner(resolved.repoRoot);
   const artifacts = enumerateArtifacts(resolved.taskDir);
+  const workflow = collectWorkflow(content);
 
   const model: StatusModel = {
     taskId: resolved.taskId,
     shortId: loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId) ?? DASH,
     title: extractTitle(content),
-    issueNumber: fm.issue_number && /^\d+$/.test(fm.issue_number) ? fm.issue_number : '',
     metadata: collectMetadata(fm),
     artifacts: { count: artifacts.length, groups: groupArtifacts(artifacts) },
-    git: collectGit(fm.branch ?? '', run),
-    platform: collectPlatform(fm, run)
+    workflow,
+    runtime: collectRuntime(resolved.taskDir, workflow, run),
+    git: collectGit(fm.branch ?? '', run)
   };
 
   for (const line of renderStatus(model)) {
@@ -295,8 +436,9 @@ export {
   collectMetadata,
   groupArtifacts,
   collectGit,
-  collectPlatform,
+  collectWorkflow,
+  collectRuntime,
   renderStatus,
   METADATA_KEYS
 };
-export type { Runner, GitInfo, PlatformInfo, StatusModel };
+export type { Runner, GitInfo, WorkflowInfo, RuntimeInfo, StatusModel };

package/lib/task/index.ts

@@ -2,6 +2,7 @@ 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)
@@ -13,6 +14,8 @@ 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
@@ -46,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);

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

@@ -41,4 +41,33 @@ function findSectionHeading(content: string, aliases: string[]): string {
   return aliases[0]!;
 }
 
-export { extractSection, findSectionHeading };
+/**
+ * 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.7",
+  "version": "0.8.1",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -43,7 +43,8 @@
     "installer"
   ],
   "dependencies": {
-    "@clack/prompts": "1.5.1",
+    "@clack/prompts": "1.7.0",
+    "@larksuiteoapi/node-sdk": "^1.68.0",
     "cross-spawn": "^7.0.6",
     "picocolors": "1.1.1",
     "semver": "^7.8.1",
@@ -57,17 +58,21 @@
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
     "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\"",
     "test:core": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
+    "check": "npm run typecheck && npm test",
     "test": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\"",
     "test:coverage": "npm run build && node --experimental-strip-types --no-warnings --test --experimental-test-coverage \"--test-coverage-exclude=tests/**\" --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"tests/**/*.test.ts\"",
     "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\""
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^25.9.1",
+    "@types/node": "^22.20.0",
     "@types/semver": "^7.7.1",
     "typescript": "~6.0"
   },
   "optionalDependencies": {
     "@lydell/node-pty": "^1.2.0-beta.12"
+  },
+  "overrides": {
+    "axios": "1.18.1"
   }
 }

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

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

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

@@ -29,7 +29,7 @@ Localized option input may be normalized before writing:
 | `中` | `Medium` |
 | `低` | `Low` |
 
-AI agents may infer `priority` and `effort` from the title and description when creating or refining tasks, but must keep date fields empty unless the user or source Issue provides explicit dates. Human edits in `task.md` take precedence.
+AI agents may infer `priority` and `effort` from the title and description when creating or refining tasks. Date fields are factual, not estimated: `start_date` is written by the analyze stage (the analysis start date) and `target_date` by the complete stage (the completion date). Human edits in `task.md` take precedence.
 
 ## GraphQL Reference
 

package/templates/.agents/rules/issue-fields.github.zh-CN.md

@@ -29,7 +29,7 @@
 | `中` | `Medium` |
 | `低` | `Low` |
 
-AI agent 在创建或修订任务时可根据标题与描述推断 `priority` 和 `effort`，但除非用户或来源 Issue 明确提供日期，否则必须保持日期字段为空。`task.md` 中人工填写的值优先。
+AI agent 在创建或修订任务时可根据标题与描述推断 `priority` 和 `effort`。日期字段为事实值、不估算：`start_date` 由 analyze 阶段写入（= 分析开始日），`target_date` 由 complete 阶段写入（= 完成日）。`task.md` 中人工填写的值优先。
 
 ## GraphQL 参考
 

package/templates/.agents/rules/next-step-output.en.md

@@ -59,7 +59,7 @@ 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.
+- 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 manual-validation 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)
@@ -77,6 +77,10 @@ This section is a **third standalone rule, co-equal with the two above**, used o
     Location: the matching row in task.md `## 审查分歧账本` · Evidence: {evidence}
   …(one entry per status=needs-human-decision row of this stage in task.md `## 审查分歧账本`)
 
+View details:
+  - All pending decisions: ai task decisions {task-ref}
+  - A single item's full background/options/impact/recommendation: ai task decisions {task-ref} <ordinal|HD-id>
+
 To resolve:
   1. In the task.md `## 人工裁决` section, record your ruling and rationale for each item above.
   2. Flip the status of the matching row in `## 审查分歧账本` from `needs-human-decision` to `human-decided`.

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

@@ -59,7 +59,7 @@ Completed at: YYYY-MM-DD HH:mm:ss
 ```
 
 - 取值命令（本地时区、不带偏移）：`date "+%Y-%m-%d %H:%M:%S"`
-- 位置：必须是整段面向用户输出的最后一行，排在所有「下一步」命令之后。若某场景在命令之后还有条件性提醒行（如 env-blocked 提醒），收尾行排在该提醒行之后。
+- 位置：必须是整段面向用户输出的最后一行，排在所有「下一步」命令之后。若某场景在命令之后还有条件性提醒行（如 manual-validation 提醒），收尾行排在该提醒行之后。
 - 该行只用于终端扫视，不写入任何产物文件或 Issue/PR 评论；完成时刻的单一事实源仍是 task.md 的 Activity Log。
 
 ## 人工裁决待办前置块（review-* 专用，{h} > 0 时）
@@ -77,6 +77,10 @@ Completed at: YYYY-MM-DD HH:mm:ss
     位置：task.md `## 审查分歧账本` 对应行 · 证据：{evidence}
   …（task.md `## 审查分歧账本` 中本阶段每个 status=needs-human-decision 行一条）
 
+查看详情：
+  - 全部待裁决项：ai task decisions {task-ref}
+  - 单项完整背景/选项/影响/建议：ai task decisions {task-ref} <序号|HD-id>
+
 完成裁决：
   1. 在 task.md `## 人工裁决` 段，逐项记录你对上述裁决项的裁定与理由。
   2. 把 `## 审查分歧账本` 中对应行的 status 由 `needs-human-decision` 翻为 `human-decided`。

package/templates/.agents/rules/no-mid-flow-questions.en.md

@@ -55,7 +55,10 @@ For every SKILL execution context not covered by any exemption above, the defaul
 
 ## Key Design Decision Marking And Ledgering
 
-When an open question is a key design decision that needs human judgment, the executor must mark the item with `[needs-human-decision]` and write the matching `HD-` row to task.md `## Review Disagreement Ledger` according to `.agents/rules/review-handshake.md`.
+When an open question is a key design decision that needs human judgment, the executor must:
+
+1. Write the decision's **detail block** (background / options / impact / recommendation) into the artifact's `## 人工裁决待办` (Pending Human Decisions) section, with a heading like `### HD-N：<title> [needs-human-decision]`; ordinary assumptions / open questions still go under `## Assumptions` / `## Open Questions` (`## 假设` / `## 未决问题`), and `## Open Questions` may keep a one-line pointer to the matching `### HD-N`.
+2. Upsert the matching `HD-` row in task.md `## Review Disagreement Ledger` according to `.agents/rules/review-handshake.md`, with `evidence` pointing to the stable anchor `<artifact>#HD-N`. The `HD-N` number is **globally unique** (scan existing `HD-(\d+)` in the ledger and take max+1, monotonically increasing across analysis / plan / code, never reused); see review-handshake.md for the allocation rule.
 
 Use these checks together:
 
@@ -64,6 +67,8 @@ Use these checks together:
 - **Small-impact exemption**: if it is only a local, reversible, low-cost execution detail, record it under `## Assumptions` instead of upgrading it to a human ruling.
 - **Fallback**: when unsure whether it is key, treat it as key; `review-*` must check whether the executor missed any `[needs-human-decision]` markings that should have been upgraded.
 
+> Use `ai task decisions <task-ref>` to view all pending decisions of a task and their detail blocks.
+
 ## Human Review Checkpoint Semantics
 
 A mandatory human review checkpoint means:
@@ -71,7 +76,7 @@ A mandatory human review checkpoint means:
 - Stop after producing the artifact: once the skill finishes an artifact such as `plan.md`, end the current invocation and wait for the user to explicitly trigger the next skill command
 - Do not pause mid-process to ask for input: do not insert interruptions such as "Do you prefer option A or B?" between execution steps
 
-If a key decision needs human judgment during execution, follow the assumptions and open questions rule above: record it in the artifact's "Open Questions" / `未决问题` section for the user to address at the review checkpoint.
+If a key decision needs human judgment during execution, follow the "Key Design Decision Marking And Ledgering" rule above: write the detail block into the artifact's `## 人工裁决待办` (Pending Human Decisions) section as `### HD-N` and upsert the `HD-` ledger row, for the user to address at the review checkpoint; ordinary open questions still go to `## Open Questions` / `未决问题`.
 
 ## Anchor Location
 

package/templates/.agents/rules/no-mid-flow-questions.zh-CN.md

@@ -55,7 +55,10 @@
 
 ## 关键设计决策标记与落账
 
-当未决问题属于需要人工裁定的关键设计决策时，执行方必须在该条目前标记 `[needs-human-decision]`，并按 `.agents/rules/review-handshake.md` 在 task.md `## 审查分歧账本` 写入 `HD-` 行。
+当未决问题属于需要人工裁定的关键设计决策时，执行方必须：
+
+1. 把该决策的**详情块**（背景 / 选项 / 影响 / 推荐）写入产物的 `## 人工裁决待办` 段，标题形如 `### HD-N：<标题> [needs-human-decision]`；普通假设 / 未决问题仍分别写 `## 假设` / `## 未决问题`（`## Assumptions` / `## Open Questions`），`## 未决问题` 可保留一行指针指向对应 `### HD-N`。
+2. 按 `.agents/rules/review-handshake.md` 在 task.md `## 审查分歧账本` upsert 对应 `HD-` 行，evidence 指向稳定锚点 `<artifact>#HD-N`。`HD-N` 编号**全局唯一**（扫描账本已有 `HD-(\d+)` 取 max+1，跨 analysis / plan / code 单调递增、禁止复用），分配规则详见 review-handshake.md。
 
 判定时同时使用以下检查：
 
@@ -64,6 +67,8 @@
 - **小影响豁免**：若它只是局部、可逆、低成本的执行细节，写入 `## 假设` 即可，不升级为人工裁决。
 - **兜底**：无法判断是否关键时按关键处理；`review-*` 需要复核执行方是否漏标应升级的 `[needs-human-decision]`。
 
+> 用户可用 `ai task decisions <task-ref>` 查看某任务全部待裁决项及其详情块。
+
 ## 人工审查检查点语义
 
 「强制性人工审查检查点」（mandatory human review checkpoint）的语义是：
@@ -71,7 +76,7 @@
 - **产出后停止**：技能完成产物（如 `plan.md`）后立即结束本轮调用，等待用户主动触发下一个技能命令
 - **不是过程中暂停征求意见**：不允许在执行步骤之间插入「请问您倾向 A 还是 B？」之类的中断
 
-如果在执行过程中发现需要用户裁定的关键决策，按上文「假设与未决问题」处理，记录到产物的「未决问题」/`Open Questions` 段落，由用户在审查检查点统一回应。
+如果在执行过程中发现需要用户裁定的关键决策，按上文「关键设计决策标记与落账」处理：详情块写入产物 `## 人工裁决待办` 的 `### HD-N`、回写 `HD-` 账本行，由用户在审查检查点统一回应；普通未决问题仍写 `## 未决问题` / `Open Questions`。
 
 ## 锚点位置