@fitlab-ai/agent-infra 0.9.10 → 0.9.11

package/lib/task/create.ts

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { isValidAgentInfraVersion, VERSION } from '../version.ts';
 import { loadShortIdByTaskId, mutateShortIdRegistry } from './short-id.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 
@@ -294,6 +295,10 @@ function recoverPublishedTask(activeRoot: string, repoRoot: string, keyDigest: s
 
 function createLocalTask(value: unknown, options: LocalTaskCreateOptions): LocalTaskCreateResult {
   const candidate = validateTaskCreateCandidate(value);
+  const agentInfraVersion = options.agentInfraVersion ?? VERSION;
+  if (!isValidAgentInfraVersion(agentInfraVersion)) {
+    throw new Error('TASK_CREATE_VERSION_INVALID: agentInfraVersion must be a valid v-prefixed semver');
+  }
   const repoRoot = fs.realpathSync.native(options.repoRoot);
   const workspaceRoot = path.join(repoRoot, '.agents', 'workspace');
   const activeRoot = path.join(workspaceRoot, 'active');
@@ -342,7 +347,7 @@ function createLocalTask(value: unknown, options: LocalTaskCreateOptions): Local
     if (!templateStat.isFile() || templateStat.isSymbolicLink()) throw new Error('TASK_CREATE_TEMPLATE_INVALID');
     const rendered = renderTask({
       template: fs.readFileSync(templatePath, 'utf8'), candidate, taskId, project, timestamp,
-      agentInfraVersion: options.agentInfraVersion ?? 'unknown', keyDigest, candidateDigest
+      agentInfraVersion, keyDigest, candidateDigest
     });
     const temporary = path.join(workspaceRoot, `.task-create.tmp.${process.pid}.${randomUUID()}`);
     fs.mkdirSync(temporary, { mode: 0o700 });

package/lib/task/current-contract.ts

@@ -0,0 +1,49 @@
+import { isValidAgentInfraVersion } from '../version.ts';
+import { parseTypedTaskFrontmatter } from './frontmatter.ts';
+import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, validateLedgerRows } from './ledger.ts';
+import type { LedgerDocument } from './ledger.ts';
+
+type CurrentTaskContractErrorCode = 'TASK_DOCUMENT_INVALID' | 'TASK_CURRENT_CONTRACT_INVALID';
+type CurrentTaskContractResult =
+  | {
+      ok: true;
+      metadata: ReturnType<typeof parseTypedTaskFrontmatter>;
+      ledger: LedgerDocument;
+    }
+  | {
+      ok: false;
+      code: CurrentTaskContractErrorCode;
+      message: string;
+    };
+
+function validateCurrentTaskContract(content: string): CurrentTaskContractResult {
+  let metadata: ReturnType<typeof parseTypedTaskFrontmatter>;
+  try {
+    metadata = parseTypedTaskFrontmatter(content);
+  } catch (error) {
+    return { ok: false, code: 'TASK_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) };
+  }
+  if (!isValidAgentInfraVersion(metadata.agent_infra_version)) {
+    return {
+      ok: false,
+      code: 'TASK_CURRENT_CONTRACT_INVALID',
+      message: `agent_infra_version must be a valid v-prefixed semver (received ${String(metadata.agent_infra_version ?? 'missing')})`
+    };
+  }
+
+  let ledger: LedgerDocument;
+  try {
+    ledger = parseLedgerDocument(content);
+  } catch (error) {
+    return { ok: false, code: 'TASK_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) };
+  }
+  if (!ledger.present) {
+    return { ok: false, code: 'TASK_CURRENT_CONTRACT_INVALID', message: `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}` };
+  }
+  const invalid = validateLedgerRows(ledger.rows);
+  if (invalid) return { ok: false, code: 'TASK_CURRENT_CONTRACT_INVALID', message: `${invalid.code}: ${invalid.message}` };
+  return { ok: true, metadata, ledger };
+}
+
+export { validateCurrentTaskContract };
+export type { CurrentTaskContractErrorCode, CurrentTaskContractResult };

package/lib/task/decision-details.ts

@@ -0,0 +1,340 @@
+type SourceLine = {
+  start: number;
+  end: number;
+  text: string;
+};
+
+type VisibleHeading = SourceLine & {
+  level: number;
+  text: string;
+};
+
+type VisibleAnchor = SourceLine & {
+  id: string;
+};
+
+type VisibleMarkdown = {
+  lines: SourceLine[];
+  headings: VisibleHeading[];
+  anchors: VisibleAnchor[];
+};
+
+type DecisionDetailBlock = {
+  id: string;
+  heading: string;
+  canonical: boolean;
+  start: number;
+  end: number;
+  content: string;
+};
+
+type DecisionDetailResolution =
+  | { status: 'found'; block: DecisionDetailBlock }
+  | { status: 'missing'; reason: string }
+  | { status: 'ambiguous'; reason: string; candidates: DecisionDetailBlock[] };
+
+type DecisionDetailDuplicate = {
+  id: string;
+  blocks: DecisionDetailBlock[];
+  repairable: boolean;
+};
+
+type DecisionDetailInspection =
+  | { ok: true; blocks: DecisionDetailBlock[] }
+  | {
+      ok: false;
+      code: 'DECISION_DETAIL_DUPLICATE';
+      message: string;
+      blocks: DecisionDetailBlock[];
+      duplicates: DecisionDetailDuplicate[];
+    };
+
+type DecisionDetailRepair =
+  | { ok: true; changed: boolean; content: string }
+  | {
+      ok: false;
+      code: 'DECISION_DETAIL_AMBIGUOUS';
+      message: string;
+      content: string;
+    };
+
+const DECISION_ID = /^(AN|PL|CD|HD)-[1-9]\d*(?=$|[\s:：])/i;
+const HEADING = /^ {0,3}(#{1,6})[ \t]+(.+?)\s*$/;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const FENCE_CLOSE = /^ {0,3}(`{3,}|~{3,})\s*$/;
+const ANCHOR = /^\s*<a\s+id=(['"])([^'"]+)\1\s*><\/a>\s*$/;
+const FIELD = /^\s*[-*]\s+\*\*([^*]+)\*\*\s*[:：]\s*/;
+const OPTION_HEADING = /^(?:方案|Option)\s+[A-Z](?:\b|\s*[:：])/i;
+
+function sourceLines(content: string): SourceLine[] {
+  const lines: SourceLine[] = [];
+  let start = 0;
+  while (start < content.length) {
+    const newline = content.indexOf('\n', start);
+    const end = newline === -1 ? content.length : newline;
+    lines.push({ start, end, text: content.slice(start, end).replace(/\r$/, '') });
+    start = newline === -1 ? content.length : newline + 1;
+  }
+  return lines;
+}
+
+function scanVisibleMarkdown(content: string): VisibleMarkdown {
+  const lines = sourceLines(content);
+  const visible: SourceLine[] = [];
+  const headings: VisibleHeading[] = [];
+  const anchors: VisibleAnchor[] = [];
+  let fence: { character: '`' | '~'; length: number } | null = null;
+
+  for (const line of lines) {
+    if (fence) {
+      const close = line.text.match(FENCE_CLOSE);
+      if (close && close[1]![0] === fence.character && close[1]!.length >= fence.length) fence = null;
+      continue;
+    }
+    const open = line.text.match(FENCE_OPEN);
+    const marker = open?.[1];
+    const info = open?.[2] ?? '';
+    if (marker && !(marker[0] === '`' && info.includes('`'))) {
+      fence = { character: marker[0] as '`' | '~', length: marker.length };
+      continue;
+    }
+    visible.push(line);
+    const heading = line.text.match(HEADING);
+    if (heading) headings.push({ ...line, level: heading[1]!.length, text: heading[2]!.trim() });
+    const anchor = line.text.match(ANCHOR);
+    if (anchor) anchors.push({ ...line, id: anchor[2]! });
+  }
+  return { lines: visible, headings, anchors };
+}
+
+function parseDecisionDetailBlocks(content: string): DecisionDetailBlock[] {
+  const scanned = scanVisibleMarkdown(content);
+  const details = scanned.headings.filter((heading) => heading.level === 3 && DECISION_ID.test(heading.text));
+  return details.map((heading) => {
+    const next = scanned.headings.find((candidate) => (
+      candidate.start > heading.start && candidate.level <= 3
+    ));
+    const end = next?.start ?? content.length;
+    return {
+      id: heading.text.match(DECISION_ID)![0]!,
+      heading: heading.text,
+      canonical: /\[needs-human-decision\]/i.test(heading.text),
+      start: heading.start,
+      end,
+      content: content.slice(heading.start, end).trim()
+    };
+  });
+}
+
+function parseDecisionEvidence(evidence: string): { ok: true; artifact: string; anchor: string } | { ok: false } {
+  const separator = evidence.indexOf('#');
+  if (separator <= 0 || evidence.indexOf('#', separator + 1) !== -1) return { ok: false };
+  const artifact = evidence.slice(0, separator);
+  const anchor = evidence.slice(separator + 1);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.md$/.test(artifact)) return { ok: false };
+  if (!anchor || /[\s\u0000-\u001f#]/.test(anchor)) return { ok: false };
+  return { ok: true, artifact, anchor };
+}
+
+function sameId(left: string, right: string): boolean {
+  return left.toUpperCase() === right.toUpperCase();
+}
+
+function resolveDecisionDetail(content: string, rowId: string, anchor: string): DecisionDetailResolution {
+  const scanned = scanVisibleMarkdown(content);
+  const blocks = parseDecisionDetailBlocks(content);
+  const explicit = scanned.anchors.filter((candidate) => candidate.id === anchor);
+  if (explicit.length > 1) {
+    return { status: 'ambiguous', reason: `evidence anchor '${anchor}' occurs more than once`, candidates: [] };
+  }
+  if (explicit.length === 1) {
+    const marker = explicit[0]!;
+    const followingLine = scanned.lines.find((line) => line.start > marker.end && line.text.trim());
+    const followingHeading = followingLine
+      ? scanned.headings.find((heading) => heading.start === followingLine.start)
+      : undefined;
+    const candidate = followingHeading?.level === 3
+      ? blocks.find((block) => block.start === followingHeading.start)
+      : undefined;
+    if (!candidate || !sameId(candidate.id, rowId) || !candidate.canonical) {
+      return { status: 'missing', reason: `evidence anchor '${anchor}' does not identify a canonical ${rowId} detail` };
+    }
+    return { status: 'found', block: candidate };
+  }
+  if (!sameId(anchor, rowId)) {
+    return { status: 'missing', reason: `evidence anchor '${anchor}' is not the ledger id '${rowId}'` };
+  }
+  const matches = blocks.filter((block) => sameId(block.id, rowId) && block.canonical);
+  if (matches.length === 0) return { status: 'missing', reason: `no canonical ${rowId} detail was found` };
+  if (matches.length > 1) {
+    return { status: 'ambiguous', reason: `more than one canonical ${rowId} detail was found`, candidates: matches };
+  }
+  return { status: 'found', block: matches[0]! };
+}
+
+const INFORMAL_SHORT_HEADING = /^(?:AN|PL|CD|HD)-[1-9]\d*[：:]\s*(?:上一轮)?简短复核$/i;
+const INFORMAL_SHORT_FRAGMENT = /^简短(?:结论|说明)$/;
+
+function isInformalShortBlock(block: DecisionDetailBlock): boolean {
+  if (block.canonical || block.content.length > 600) return false;
+  if (!INFORMAL_SHORT_HEADING.test(block.heading)) return false;
+  const scanned = scanVisibleMarkdown(block.content);
+  const bodyLines = scanned.lines
+    .filter((line) => !scanned.headings.some((heading) => heading.start === line.start) && line.text.trim())
+    .map((line) => line.text);
+  if (bodyLines.length === 0 || bodyLines.length > 2) return false;
+  const fragments = bodyLines.map((line) => line.match(/^\s*[-*]\s+([^\s].*?)\s*$/)?.[1] ?? null);
+  if (fragments.some((fragment) => fragment === null)) return false;
+  return fragments.every((fragment) => INFORMAL_SHORT_FRAGMENT.test(fragment!));
+}
+
+function hasDirectPrecedingAnchor(block: DecisionDetailBlock, scanned: VisibleMarkdown): boolean {
+  return scanned.anchors.some((anchor) => (
+    anchor.end < block.start
+    && !scanned.lines.some((line) => line.start > anchor.end && line.start < block.start && line.text.trim())
+  ));
+}
+
+function inspectDecisionDetailDuplicates(content: string): DecisionDetailInspection {
+  const blocks = parseDecisionDetailBlocks(content);
+  const scanned = scanVisibleMarkdown(content);
+  const grouped = new Map<string, DecisionDetailBlock[]>();
+  for (const block of blocks) {
+    const key = block.id.toUpperCase();
+    const group = grouped.get(key) ?? [];
+    group.push(block);
+    grouped.set(key, group);
+  }
+  const duplicates: DecisionDetailDuplicate[] = [];
+  for (const group of grouped.values()) {
+    if (group.length < 2) continue;
+    const canonical = group.filter((block) => block.canonical);
+    const repairable = canonical.length === 1 && group.every((block) => (
+      block.canonical || (!hasDirectPrecedingAnchor(block, scanned) && isInformalShortBlock(block))
+    ));
+    duplicates.push({ id: canonical[0]?.id ?? group[0]!.id, blocks: group, repairable });
+  }
+  if (duplicates.length === 0) return { ok: true, blocks };
+  const summary = duplicates.map((duplicate) => {
+    const types = duplicate.blocks.map((block) => block.canonical ? 'canonical' : 'informal').join(', ');
+    return `${duplicate.id} (${duplicate.blocks.length} blocks: ${types}${duplicate.repairable ? '; safe repair available' : ''})`;
+  }).join(', ');
+  return {
+    ok: false,
+    code: 'DECISION_DETAIL_DUPLICATE',
+    message: `Duplicate decision detail ids: ${summary}`,
+    blocks,
+    duplicates
+  };
+}
+
+function repairDecisionDetailDuplicates(content: string): DecisionDetailRepair {
+  const inspection = inspectDecisionDetailDuplicates(content);
+  if (inspection.ok) return { ok: true, changed: false, content };
+  const unsafe = inspection.duplicates.filter((duplicate) => !duplicate.repairable);
+  if (unsafe.length > 0) {
+    return {
+      ok: false,
+      code: 'DECISION_DETAIL_AMBIGUOUS',
+      message: `Cannot safely repair duplicate decision detail ids: ${unsafe.map((duplicate) => duplicate.id).join(', ')}`,
+      content
+    };
+  }
+  const removals = inspection.duplicates.flatMap((duplicate) => duplicate.blocks.filter((block) => !block.canonical));
+  let repaired = content;
+  for (const block of removals.sort((left, right) => right.start - left.start)) {
+    repaired = repaired.slice(0, block.start) + repaired.slice(block.end);
+  }
+  return { ok: true, changed: repaired !== content, content: repaired };
+}
+
+type FieldKey = 'decision' | 'why' | 'impact' | 'risk' | 'analogy' | 'recommend' | 'reason' | 'implementation';
+
+const FIELD_KEYS: Record<string, FieldKey> = {
+  '为什么现在要决定': 'why', 'why decide now': 'why', 'why a decision is needed now': 'why',
+  '要决定什么': 'decision', 'what to decide': 'decision', 'what needs a decision': 'decision',
+  '会影响什么': 'impact', 'what it affects': 'impact', 'what this affects': 'impact',
+  '如果选错或暂不处理': 'risk', 'if wrong or postponed': 'risk',
+  'what could go wrong': 'risk',
+  '打个比方': 'analogy', '例子': 'analogy', 'example': 'analogy',
+  '建议选哪个': 'recommend', 'recommended option': 'recommend', 'recommended choice': 'recommend',
+  '为什么这样建议': 'reason', 'why this recommendation': 'reason', 'why this choice': 'reason',
+  '是否需要实现': 'implementation', 'implementation required': 'implementation'
+};
+
+const TERMINAL_FIELD_KEYS = new Set<FieldKey>(['recommend', 'reason', 'implementation']);
+
+function normalizeDecisionDetailForDisplay(block: DecisionDetailBlock): string {
+  const body = block.content;
+  const scanned = scanVisibleMarkdown(body);
+  const heading = scanned.headings.find((candidate) => candidate.level === 3);
+  if (!heading) return body.trim();
+  const options = scanned.headings.filter((candidate) => candidate.level === 4 && OPTION_HEADING.test(candidate.text));
+  const optionRanges = options.map((option, index) => ({
+    start: option.start,
+    end: options[index + 1]?.start
+      ?? scanned.headings.find((candidate) => candidate.start > option.start && candidate.level <= 3)?.start
+      ?? scanned.lines.find((line) => (
+        line.start > option.start
+        && FIELD.test(line.text)
+        && TERMINAL_FIELD_KEYS.has(FIELD_KEYS[line.text.match(FIELD)![1]!.trim().toLowerCase()] as FieldKey)
+      ))?.start
+      ?? body.length
+  }));
+  const topLines = scanned.lines.filter((line) => (
+    line.start > heading.end && !optionRanges.some((range) => line.start >= range.start && line.start < range.end)
+  ));
+  const fields: { key: FieldKey | null; line: SourceLine }[] = [];
+  for (const line of topLines) {
+    const match = line.text.match(FIELD);
+    if (!match) continue;
+    const key = FIELD_KEYS[match[1]!.trim().toLowerCase()];
+    fields.push({ key: key ?? null, line });
+  }
+  if (fields.some((field) => field.key === null)) return body.trim();
+  const byKey = new Map<FieldKey, string>();
+  const selectedRanges: { start: number; end: number }[] = [];
+  for (let index = 0; index < fields.length; index += 1) {
+    const field = fields[index]!;
+    if (!field.key) continue;
+    const nextOption = optionRanges.find((range) => range.start > field.line.start)?.start ?? body.length;
+    const end = Math.min(fields[index + 1]?.line.start ?? body.length, nextOption);
+    const value = body.slice(field.line.start, end).trim();
+    byKey.set(field.key, value);
+    selectedRanges.push({ start: field.line.start, end });
+  }
+  selectedRanges.push(...optionRanges);
+  const required: FieldKey[] = ['decision', 'why', 'impact', 'recommend', 'reason'];
+  if (required.some((key) => !byKey.has(key)) || options.length < 2) return body.trim();
+  const sortedRanges = selectedRanges.sort((left, right) => left.start - right.start);
+  let cursor = heading.end;
+  for (const range of sortedRanges) {
+    if (/\S/.test(body.slice(cursor, range.start))) return body.trim();
+    cursor = Math.max(cursor, range.end);
+  }
+  if (/\S/.test(body.slice(cursor))) return body.trim();
+  const ordered: string[] = [
+    byKey.get('decision')!, byKey.get('why')!, byKey.get('impact')!
+  ];
+  for (const optional of ['risk', 'analogy'] as const) if (byKey.has(optional)) ordered.push(byKey.get(optional)!);
+  ordered.push(...optionRanges.map((range) => body.slice(range.start, range.end).trim()));
+  ordered.push(byKey.get('recommend')!, byKey.get('reason')!);
+  if (byKey.has('implementation')) ordered.push(byKey.get('implementation')!);
+  return [body.slice(heading.start, heading.end).trim(), ...ordered].join('\n\n').trim();
+}
+
+export {
+  inspectDecisionDetailDuplicates,
+  normalizeDecisionDetailForDisplay,
+  parseDecisionDetailBlocks,
+  parseDecisionEvidence,
+  repairDecisionDetailDuplicates,
+  resolveDecisionDetail
+};
+export type {
+  DecisionDetailBlock,
+  DecisionDetailDuplicate,
+  DecisionDetailInspection,
+  DecisionDetailRepair,
+  DecisionDetailResolution
+};

package/lib/task/decision-intents.ts

@@ -10,7 +10,7 @@ import {
   renderImplementationInputs,
   selectDeclaredImplementationInput
 } from './implementation-inputs.ts';
-import { LEDGER_COLUMNS, LEDGER_HEADINGS, parseLedger } from './ledger.ts';
+import { LEDGER_COLUMNS, LEDGER_HEADINGS, LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument } from './ledger.ts';
 import type { LedgerRow } from './ledger.ts';
 import { resolveTaskContext } from './resolve-ref.ts';
 import { extractSection, extractSubSection, findSectionHeading } from './sections.ts';
@@ -90,7 +90,12 @@ function applyHumanDecision(request: HumanDecisionRequest, options: TaskWriteOpt
   if (resolved.state !== 'active' && !stateOverride) return failed('TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   let content: string;
   let rows: LedgerRow[];
-  try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); rows = parseLedger(content); }
+  try {
+    content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    const ledger = parseLedgerDocument(content);
+    if (!ledger.present) return failed(LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, resolved.taskId);
+    rows = ledger.rows as LedgerRow[];
+  }
   catch (error) { return failed('DECISION_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId); }
 
   const direct = rows.filter((row) => row.id.toUpperCase() === request.selector.toUpperCase());

package/lib/task/events.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 
-import { appendActivityEntry, locateActivityLog, pairEntries } from './activity-log.ts';
+import { appendActivityEntry, locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
 import {
   buildArtifactLinkSection,
   artifactName,
@@ -21,9 +21,9 @@ import {
   parseImplementationInputs,
   renderImplementationInputs
 } from './implementation-inputs.ts';
-import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
 import type { ReviewStage } from './ledger.ts';
-import { parseReviewSummary } from './review-artifacts.ts';
+import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { findSectionHeading } from './sections.ts';
 import { validateLifecycleExecution } from './lifecycle-execution.ts';
@@ -50,6 +50,7 @@ type TaskEventErrorCode =
   | 'EVENT_UNKNOWN' | 'EVENT_PAYLOAD_INVALID' | 'EVENT_TRANSITION_INVALID'
   | 'EVENT_LOG_MISSING' | 'EVENT_START_MISSING' | 'EVENT_ALREADY_COMPLETED'
   | 'EVENT_LOG_CONFLICT' | 'EVENT_ARTIFACT_CONFLICT' | 'EVENT_FINDING_COUNT_MISMATCH'
+  | 'EVENT_VERDICT_INVALID'
   | 'EVENT_ORCHESTRATION_COMMIT_FAILED'
   | ArtifactErrorCode | TaskWriteErrorCode;
 type TaskEventRequest = {
@@ -151,7 +152,9 @@ function validateReviewFindingCounts(
 ): TaskEventError | null {
   const stage = REVIEW_LEDGER_STAGES[family];
   if (!stage || !artifactPath) return null;
-  const rows = parseLedger(content);
+  const ledger = parseLedgerDocument(content);
+  if (!ledger.present) return { code: 'EVENT_FINDING_COUNT_MISMATCH', message: `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}` };
+  const rows = ledger.rows;
   const invalid = validateLedgerRows(rows);
   if (invalid) return { code: 'TASK_DOCUMENT_INVALID', message: `${invalid.code}: ${invalid.message}` };
   const expected = summarizeLedgerStage(rows, stage).unresolvedFindingCounts;
@@ -173,6 +176,8 @@ function validateReviewFindingCounts(
       message: parsed.ok ? 'review summary finding counts are not finalized' : parsed.message
     };
   }
+  const canonical = resolveCanonicalVerdict(parsed.summary);
+  if (!canonical.ok) return { code: 'EVENT_VERDICT_INVALID', message: `${canonical.code}: ${canonical.message}` };
   const report = parsed.summary.counts;
   const reportVerdict = parsed.summary.verdict === 'Approved'
     ? 'approved'
@@ -370,7 +375,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   catch (error) { return failed(request, { code: 'TASK_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
   const section = locateActivityLog(content);
   if (!section) return failed(request, { code: 'EVENT_LOG_MISSING', message: 'task has no unique Activity Log section' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
-  const rows = pairEntries(section.entries);
+  const rows = startedBackedRows(pairEntries(section.entries));
   let normalized = request;
   let artifactContext: ArtifactContextResult | null = null;
   const initialParts = eventParts(request.event);

package/lib/task/index.ts

@@ -1,34 +1,33 @@
 const USAGE = `Usage: ai task <command> [options]
 
 Commands:
-  cat [--task <ref>] <artifact | N>      Print a task artifact (by name or number)
-  decisions, d [--task <ref>] [-i item]  List review decisions, or show one item's detail
-  files [--task <ref>]                   List artifacts in a task dir (numbered)
-  grep <pattern> [--current|--task <ref>] Literal search across task artifacts (global by default)
-  issue-body [--task <ref>] [--template] Print a deterministic Issue body from task.md
-  log [--task <ref>]                     Render a task's activity log as a timeline
+  cat [--task <ref> | -t <ref>] <artifact | N> Print a task artifact (by name or number)
+  decisions, d [--task <ref> | -t <ref>] [--item <selector> | -i <selector>] List review decisions, or show one item's detail
+  files [--task <ref> | -t <ref>]        List artifacts in a task dir (numbered)
+  grep [--current | --task <ref> | -t <ref>] <pattern> Literal search in the current or selected task
+  issue-body [--task <ref> | -t <ref>] [--template <path>] Print a deterministic Issue body from task.md
+  log [--task <ref> | -t <ref>]          Render a task's activity log as a timeline
   ls [--all | --blocked | --completed]   List tasks (default: active)
-  show [--task <ref>]                    Print a task.md
-  status [--task <ref>]                  Aggregated status view (metadata / artifacts / git / platform)
+  show [--task <ref> | -t <ref>]         Print a task.md
+  status [--task <ref> | -t <ref>]       Aggregated status view (metadata / artifacts / git / platform)
 
 Examples:
-  ai task cat 11 analysis
   ai task cat analysis
-  ai task cat 11 3
-  ai task decisions 11
+  ai task cat --task 11 analysis
+  ai task decisions --task 11
   ai task decisions --item 1
-  ai task d 11 PL-3 --format markdown
-  ai task files 11
+  ai task d --task 11 --item PL-3 --format markdown
+  ai task files --task 11
   ai task grep resolveArtifact
   ai task grep resolveArtifact --current
-  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 grep resolveArtifact --task 11
+  ai task issue-body --task 11
+  ai task issue-body --task 11 --template .github/ISSUE_TEMPLATE/05_other.yml
+  ai task log --task 11
   ai task ls
-  ai task show 11
-  ai task show TASK-20260612-162737
-  ai task status 11
+  ai task show --task 11
+  ai task show --task TASK-20260612-162737
+  ai task status --task 11
 
 Run 'ai task <command> --help' for details.`;
 

package/lib/task/ledger-intents.ts

@@ -7,7 +7,7 @@ import {
   parseImplementationInputs,
   renderImplementationInputs
 } from './implementation-inputs.ts';
-import { LEDGER_COLUMNS, LEDGER_HEADINGS, nextHdId, parseLedger, validateLedgerRows } from './ledger.ts';
+import { LEDGER_COLUMNS, LEDGER_HEADINGS, LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, nextHdId, parseLedgerDocument, validateLedgerRows } from './ledger.ts';
 import type { LedgerRow, ReviewStage } from './ledger.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { writeTask } from './write.ts';
@@ -61,6 +61,7 @@ function normalizedEvidence(value: string): string {
 
 function ledgerReadErrorCode(error: unknown): string {
   const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+  if (code === LEDGER_SECTION_MISSING_CODE) return code;
   return code === 'TABLE_DUPLICATE_KEY' ? 'LEDGER_DUPLICATE_ID' : 'LEDGER_DOCUMENT_INVALID';
 }
 
@@ -96,12 +97,7 @@ function rowMutation(row: LedgerRow): TaskMutation {
 }
 
 function ledgerSectionMutation(content: string): TaskMutation[] {
-  if (/^##\s+(审查分歧账本|Review Disagreement Ledger)\s*$/m.test(content)) return [];
-  const english = /^##\s+Activity Log\s*$/m.test(content);
-  return [{
-    kind: 'section', aliases: LEDGER_HEADINGS, heading: english ? 'Review Disagreement Ledger' : '审查分歧账本',
-    body: `| ${LEDGER_COLUMNS.join(' | ')} |\n|----|-------|-------|----------|--------|----------|`
-  }];
+  return [];
 }
 
 function implementationInputMutation(content: string, rows: Parameters<typeof renderImplementationInputs>[0]): TaskMutation {
@@ -127,7 +123,9 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
   let rows: LedgerRow[];
   try {
     content = fs.readFileSync(resolved.taskMdPath, 'utf8');
-    rows = parseLedger(content);
+    const ledger = parseLedgerDocument(content);
+    if (!ledger.present) return failed(intent, LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, resolved.taskId);
+    rows = ledger.rows as LedgerRow[];
   } catch (error) {
     return failed(intent, ledgerReadErrorCode(error), error instanceof Error ? error.message : String(error), resolved.taskId);
   }

package/lib/task/ledger.ts

@@ -20,6 +20,10 @@ type LedgerRow = {
   /** Zero-based line within the normalized ledger section body. */
   sourceLine: number;
 };
+type LedgerDocument = {
+  present: boolean;
+  rows: readonly LedgerRow[];
+};
 
 type ReviewStage = 'analysis' | 'plan' | 'code';
 type ReviewSeverity = 'blocker' | 'major' | 'minor';
@@ -40,6 +44,8 @@ const LEDGER_TERMINAL = new Set(['confirmed', 'closed', 'human-decided']);
 // Statuses that represent a decision row awaiting or carrying a human ruling.
 const HUMAN_DECISION_STATUSES = new Set(['needs-human-decision', 'human-decided']);
 const FINDING_STATUSES = new Set(['open', 'accepted', 'adjusted', 'refuted', 'cannot-judge', 'confirmed', 'needs-human-decision', 'closed', 'human-decided']);
+const LEDGER_SECTION_MISSING_CODE = 'LEDGER_SECTION_MISSING';
+const LEDGER_SECTION_MISSING_MESSAGE = 'review disagreement ledger section is missing';
 
 function isReviewStage(stage: string): stage is ReviewStage {
   return stage === 'analysis' || stage === 'plan' || stage === 'code';
@@ -48,12 +54,16 @@ function isReviewStage(stage: string): stage is ReviewStage {
 // 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[] {
+function parseLedgerDocument(content: string): LedgerDocument {
   const table = parseTable(content, { sectionAliases: LEDGER_HEADINGS, columns: LEDGER_COLUMNS });
-  return table?.rows.map(({ values, sourceLine }) => ({
-    id: values.id!, stage: values.stage!, round: values.round!, severity: values.severity!,
-    status: values.status!, evidence: values.evidence!, sourceLine
-  })) ?? [];
+  if (!table) return { present: false, rows: [] };
+  return {
+    present: true,
+    rows: table.rows.map(({ values, sourceLine }) => ({
+      id: values.id!, stage: values.stage!, round: values.round!, severity: values.severity!,
+      status: values.status!, evidence: values.evidence!, sourceLine
+    }))
+  };
 }
 
 function validateLedgerRows(rows: readonly LedgerRow[]): LedgerValidationError | null {
@@ -130,5 +140,5 @@ function nextHdId(rows: readonly LedgerRow[]): string {
   return `HD-${max + 1}`;
 }
 
-export { LEDGER_HEADINGS, LEDGER_COLUMNS, parseLedger, nextHdId, isReviewStage, validateLedgerRows, summarizeLedgerStage, LEDGER_TERMINAL, HUMAN_DECISION_STATUSES };
-export type { LedgerRow, ReviewStage, ReviewSeverity, LedgerValidationError, LedgerStageStatus };
+export { LEDGER_HEADINGS, LEDGER_COLUMNS, parseLedgerDocument, nextHdId, isReviewStage, validateLedgerRows, summarizeLedgerStage, LEDGER_TERMINAL, HUMAN_DECISION_STATUSES, LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE };
+export type { LedgerRow, LedgerDocument, ReviewStage, ReviewSeverity, LedgerValidationError, LedgerStageStatus };