@fitlab-ai/agent-infra 0.9.1 → 0.9.2

package/lib/task/artifact-lifecycle.ts

@@ -5,6 +5,7 @@ import { resolveTaskRef } from './resolve-ref.ts';
 import type { ResolveTaskRefErrorCode, TaskWorkspaceState } from './resolve-ref.ts';
 import { locateActivityLog } from './activity-log.ts';
 import { parseImplementationInputs, selectPendingImplementationInput } from './implementation-inputs.ts';
+import { parseVerdict } from './review-artifacts.ts';
 import { extractSection, findSectionHeading } from './sections.ts';
 
 const artifactFamilyCatalog = [
@@ -239,21 +240,6 @@ function resolveReviewedInput(
   }
 }
 
-function extractMarkdownSection(content: string, names: readonly string[]): string {
-  const lines = content.split(/\r?\n/);
-  const allowed = new Set(names);
-  const start = lines.findIndex((line) => {
-    const match = /^##\s+(.+?)\s*$/.exec(line.trim());
-    return Boolean(match?.[1] && allowed.has(match[1]));
-  });
-  if (start === -1) return '';
-  let end = lines.length;
-  for (let index = start + 1; index < lines.length; index += 1) {
-    if (/^##\s+/.test(lines[index]!)) { end = index; break; }
-  }
-  return lines.slice(start + 1, end).join('\n');
-}
-
 function assertWritableInventory(inventory: ArtifactInventoryResult): ArtifactError | null {
   if (inventory.status === 'failed') return inventory.error;
   const blockers = inventory.diagnostics.filter((item) => BLOCKING_DIAGNOSTICS.has(item.code));
@@ -398,29 +384,6 @@ function resolveDecisionImplementationInput(
   catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
 }
 
-function normalizeVerdict(value: string): 'Approved' | 'Changes Requested' | 'Rejected' | null {
-  const normalized = value.trim().toLowerCase();
-  if (normalized === '通过' || normalized === 'approved') return 'Approved';
-  if (normalized === '需要修改' || normalized === 'changes requested') return 'Changes Requested';
-  if (normalized === '拒绝' || normalized === 'rejected') return 'Rejected';
-  return null;
-}
-
-function parseVerdict(file: string): { ok: true; verdict: string } | { ok: false; message: string } {
-  let content: string;
-  try { content = fs.readFileSync(file, 'utf8'); }
-  catch (error) { return { ok: false, message: String(error) }; }
-  const summary = extractMarkdownSection(content, ['审查摘要', 'Review Summary']);
-  const verdictMatch = /^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.+?)\s*$/im.exec(summary);
-  const verdict = verdictMatch?.[1] ? normalizeVerdict(verdictMatch[1]) : null;
-  if (!verdict) return { ok: false, message: `cannot parse verdict in ${path.basename(file)}` };
-  if (verdict !== 'Approved') return { ok: true, verdict };
-  const findings = /^[-*]?\s*\*\*(?:发现（AI 可处理）|Findings \(AI-actionable\))\*\*[:：]\s*(.+?)\s*$/im.exec(summary)?.[1];
-  const counts = findings?.match(/(\d+)\s*(?:阻塞项|blockers?).*?(\d+)\s*(?:主要|majors?).*?(\d+)\s*(?:次要|minors?)/i);
-  if (!counts) return { ok: false, message: `cannot parse findings count in ${path.basename(file)}` };
-  return { ok: true, verdict: counts.slice(1).some((value) => Number(value) > 0) ? 'Approved-with-issues' : 'Approved' };
-}
-
 function validateCompletedArtifact(taskDir: string, family: ArtifactFamily, name: string, round?: number): { ok: true; artifact: ArtifactIdentity } | { ok: false; error: ArtifactError } {
   if (path.basename(name) !== name) return { ok: false, error: { code: 'ARTIFACT_PATH_INVALID', message: 'artifact must be a top-level basename' } };
   const parsed = parseArtifactName(name);

package/lib/task/commands/decisions.ts

@@ -10,8 +10,9 @@ import { extractSubSection } from '../sections.ts';
 const USAGE = `Usage: ai task decisions [--task <ref> | -t <ref>] [--item <selector> | -i <selector>] [options]
        ai task decisions <ref> [selector] [options]
 
-Lists decision items recorded in a task's review disagreement
-ledger, or prints the full detail block for a single item. Read-only.
+Shows what still needs a maintainer's decision. Without a selector, it lists
+the choices. With a selector, it shows the explanation and how to respond.
+Read-only.
 
   Omit <ref>     Resolve the unique active task for the current branch.
   <ref>          Legacy positional task ref.
@@ -150,29 +151,31 @@ function findDecisionRecord(id: string, content: string): string[] {
 function titleOf(row: LedgerRow, taskDir: string): string {
   const block = findDetailBlock(row, taskDir);
   if (block) {
-    return block
+    const title = block
       .split('\n')[0]!
       .replace(/^###\s+/, '')
       .replace(/\s*\[needs-human-decision\]\s*$/, '')
       .trim();
+    return title.replace(new RegExp(`^${row.id}\\s*[:：]\\s*`, 'i'), '').trim();
   }
-  return row.evidence || '(无详情)';
+  return '(explanation unavailable)';
+}
+
+function trackingOf(row: LedgerRow): string {
+  return `stage=${row.stage} · severity=${row.severity} · status=${row.status} · evidence=${row.evidence}`;
 }
 
 function renderList(rows: LedgerRow[], format: string, taskDir: string): void {
   if (rows.length === 0) {
-    process.stdout.write('无待裁决项。\n');
+    process.stdout.write('No pending decisions.\n');
     return;
   }
-  const headers = ['#', 'ID', 'STAGE', 'SEVERITY', 'STATUS', 'EVIDENCE', 'TITLE'];
+  const headers = ['#', 'CHOICE', 'WHAT NEEDS A DECISION', 'TRACKING'];
   const data = rows.map((r, i) => [
     String(i + 1),
     r.id,
-    r.stage,
-    r.severity,
-    r.status,
-    r.evidence,
-    titleOf(r, taskDir)
+    titleOf(r, taskDir),
+    trackingOf(r)
   ]);
   if (format === 'markdown') {
     const sep = headers.map(() => '---');
@@ -181,10 +184,29 @@ function renderList(rows: LedgerRow[], format: string, taskDir: string): void {
       `| ${sep.join(' | ')} |`,
       ...data.map((row) => `| ${row.join(' | ')} |`)
     ];
-    process.stdout.write(`${md.join('\n')}\n`);
+    process.stdout.write(`${md.join('\n')}\n\nView one item: ai task decisions <task-ref> <ordinal|ledger-id>\n`);
     return;
   }
-  process.stdout.write(`${formatTable(headers, data).join('\n')}\n`);
+  process.stdout.write(`${formatTable(headers, data).join('\n')}\n\nView one item: ai task decisions <task-ref> <ordinal|ledger-id>\n`);
+}
+
+function renderTracking(row: LedgerRow, format: string): string[] {
+  if (format === 'markdown') {
+    return [
+      '**Tracking**',
+      `- stage: \`${row.stage}\``,
+      `- severity: \`${row.severity}\``,
+      `- status: \`${row.status}\``,
+      `- evidence: \`${row.evidence}\``
+    ];
+  }
+  return [
+    'Tracking:',
+    `stage: ${row.stage}`,
+    `severity: ${row.severity}`,
+    `status: ${row.status}`,
+    `evidence: ${row.evidence}`
+  ];
 }
 
 function renderDetail(
@@ -201,25 +223,36 @@ function renderDetail(
   }
   const r = selected.row;
   const block = findDetailBlock(r, taskDir);
+  const title = titleOf(r, taskDir);
   const lines: string[] = [];
+  const decided = r.status === 'human-decided';
   if (format === 'markdown') {
-    lines.push(`**${r.id}** (${r.stage}/${r.severity}) · status=\`${r.status}\` · evidence: \`${r.evidence}\``, '');
+    lines.push(`## ${decided ? 'Decision already recorded' : 'Decision needed'}: ${title}`, '');
+    if (!decided) {
+      lines.push('**How to record your choice**', `\`ai decide <task-ref> ${r.id} <your choice and rationale>\``, '');
+    }
+    lines.push('**Original context**', '');
   } else {
-    lines.push(`${r.id} (${r.stage}/${r.severity}) status=${r.status}`, `evidence: ${r.evidence}`, '');
+    lines.push(`${decided ? 'Decision already recorded' : 'Decision needed'}: ${title}`, '');
+    if (!decided) {
+      lines.push('How to record your choice:', `ai decide <task-ref> ${r.id} <your choice and rationale>`, '');
+    }
+    lines.push('Original context:');
   }
   if (block) {
     lines.push(block);
   } else {
     lines.push(
-      `（详情块未找到：未在任务产物中定位到 \`### ${r.id}\` 锚点，可能为历史产物或尚未写入；evidence 指向 ${r.evidence}）`
+      `This older task does not include a full explanation for ${r.id}.`,
+      'Use the tracking reference below to find the original context.'
     );
   }
-  if (r.status === 'human-decided') {
+  if (decided) {
     const record = findDecisionRecord(r.id, content);
-    if (record.length) {
-      lines.push('', '人工裁定：', ...record);
-    }
+    lines.push('', format === 'markdown' ? '**Recorded choice**' : 'Recorded choice:');
+    lines.push(...(record.length ? record : ['No separate ruling record was found.']));
   }
+  lines.push('', ...renderTracking(r, format));
   process.stdout.write(`${lines.join('\n')}\n`);
 }
 

package/lib/task/delegation-receipts.ts

@@ -0,0 +1,170 @@
+import { randomUUID } from 'node:crypto';
+
+import type { AgentClientId } from '../agent-clients/types.ts';
+
+type DelegationRole = 'executor' | 'reviewer';
+type DelegationStage = 'analysis' | 'review-analysis' | 'plan' | 'review-plan' | 'code' | 'review-code' | 'commit';
+type DelegationStatus = 'prepared' | 'activated' | 'stage-completed' | 'sealed' | 'consumed' | 'aborted' | 'expired';
+
+type DelegationReceipt = Readonly<{
+  id: string;
+  taskId: string;
+  runId: string;
+  role: DelegationRole;
+  stage: DelegationStage;
+  round: number;
+  artifact: string;
+  client: AgentClientId;
+  requestedModel: string | null;
+  actualModel: string | null;
+  modelFallbackReason: string | null;
+  parentId: string | null;
+  childId: string | null;
+  spawnMode: string | null;
+  agent: string | null;
+  status: DelegationStatus;
+  beforeFingerprint: string;
+  afterFingerprint: string | null;
+  changedPaths: readonly string[];
+  createdAt: string;
+  activatedAt: string | null;
+  sealedAt: string | null;
+  consumedAt: string | null;
+}>;
+
+type ReceiptFailure = Readonly<{ ok: false; code: string; message: string; receipt?: never }>;
+type ReceiptSuccess = Readonly<{ ok: true; receipt: DelegationReceipt; code?: never; message?: never }>;
+type ReceiptResult = ReceiptSuccess | ReceiptFailure;
+
+const MANAGED_AGENTS = {
+  'agent-infra-lifecycle-executor': 'executor',
+  'agent-infra-lifecycle-reviewer': 'reviewer'
+} as const;
+
+function managedDelegationRole(nativeAgent: string): DelegationRole | null {
+  return MANAGED_AGENTS[nativeAgent as keyof typeof MANAGED_AGENTS] ?? null;
+}
+
+function fail(code: string, message: string): ReceiptFailure {
+  return { ok: false, code, message };
+}
+
+function prepareDelegation(
+  input: Omit<DelegationReceipt, 'id' | 'actualModel' | 'modelFallbackReason' | 'parentId' | 'childId' | 'spawnMode' | 'agent' | 'status' | 'afterFingerprint' | 'changedPaths' | 'createdAt' | 'activatedAt' | 'sealedAt' | 'consumedAt'>,
+  options: { id?: () => string; now?: () => string } = {}
+): DelegationReceipt {
+  return Object.freeze({
+    ...input,
+    id: (options.id ?? randomUUID)(),
+    actualModel: null,
+    modelFallbackReason: null,
+    parentId: null,
+    childId: null,
+    spawnMode: null,
+    agent: null,
+    status: 'prepared' as const,
+    afterFingerprint: null,
+    changedPaths: Object.freeze([]),
+    createdAt: (options.now ?? (() => new Date().toISOString()))(),
+    activatedAt: null,
+    sealedAt: null,
+    consumedAt: null
+  });
+}
+
+function activateDelegation(
+  receipt: DelegationReceipt,
+  event: Readonly<{
+    nativeAgent: string;
+    childId: string;
+    parentId: string;
+    spawnMode: string;
+    actualModel?: string;
+    modelFallbackReason?: string;
+  }>,
+  options: { now?: () => string } = {}
+): ReceiptResult {
+  const managedRole = managedDelegationRole(event.nativeAgent);
+  if (!managedRole) return fail('DELEGATION_IGNORED', `subagent '${event.nativeAgent}' is not lifecycle-managed`);
+  if (receipt.status !== 'prepared') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected prepared`);
+  if (managedRole !== receipt.role) return fail('DELEGATION_ROLE_MISMATCH', `managed role ${managedRole} does not match ${receipt.role}`);
+  if (!event.parentId || (receipt.parentId !== null && event.parentId !== receipt.parentId) || !event.childId || event.childId === event.parentId) {
+    return fail('DELEGATION_IDENTITY_INVALID', 'native parent/child identity does not match the prepared delegation');
+  }
+  if (event.spawnMode !== 'fresh') return fail('DELEGATION_FORK_FORBIDDEN', `spawn mode '${event.spawnMode}' is not fresh`);
+  const actualModel = event.actualModel ?? null;
+  if (actualModel && receipt.requestedModel && actualModel !== receipt.requestedModel && !event.modelFallbackReason) {
+    return fail('DELEGATION_MODEL_FALLBACK_UNRECORDED', 'actual model differs from requested model without a fallback reason');
+  }
+  return { ok: true, receipt: Object.freeze({
+    ...receipt,
+    status: 'activated',
+    parentId: event.parentId,
+    childId: event.childId,
+    spawnMode: event.spawnMode,
+    actualModel,
+    modelFallbackReason: event.modelFallbackReason ?? null,
+    activatedAt: (options.now ?? (() => new Date().toISOString()))()
+  }) };
+}
+
+function completeDelegationStage(
+  receipt: DelegationReceipt,
+  event: Readonly<{ stage: DelegationStage; round: number; artifact: string; agent: string }>
+): ReceiptResult {
+  if (receipt.status !== 'activated') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected activated`);
+  if (event.stage !== receipt.stage || event.round !== receipt.round || event.artifact !== receipt.artifact) {
+    return fail('DELEGATION_STAGE_MISMATCH', 'stage completion identity does not match the active delegation');
+  }
+  const acceptedAgents = receipt.client === 'claude-code' ? ['claude', 'claude-code'] : [receipt.client];
+  if (!acceptedAgents.includes(event.agent)) {
+    return fail('DELEGATION_AGENT_MISMATCH', `stage agent '${event.agent}' does not match client '${receipt.client}'`);
+  }
+  return { ok: true, receipt: Object.freeze({ ...receipt, status: 'stage-completed', agent: event.agent }) };
+}
+
+function sealDelegation(
+  receipt: DelegationReceipt,
+  event: Readonly<{ childId: string; exitCode: number; afterFingerprint: string; changedPaths: readonly string[] }>,
+  options: { now?: () => string } = {}
+): ReceiptResult {
+  if (receipt.status !== 'stage-completed') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected stage-completed`);
+  if (event.childId !== receipt.childId || event.exitCode !== 0) return fail('DELEGATION_STOP_INVALID', 'native stop identity or exit status is invalid');
+  if (receipt.role === 'reviewer') {
+    const taskRoot = `.agents/workspace/active/${receipt.taskId}/`;
+    const allowed = new Set([
+      `${taskRoot}${receipt.artifact}`,
+      `${taskRoot}task.md`,
+      `${taskRoot}orchestration.json`
+    ]);
+    const disallowed = event.changedPaths.find((entry) => !allowed.has(entry));
+    if (disallowed) return fail('DELEGATION_REVIEWER_WRITE_FORBIDDEN', `reviewer changed forbidden path '${disallowed}'`);
+  }
+  return { ok: true, receipt: Object.freeze({
+    ...receipt,
+    status: 'sealed',
+    afterFingerprint: event.afterFingerprint,
+    changedPaths: Object.freeze([...event.changedPaths]),
+    sealedAt: (options.now ?? (() => new Date().toISOString()))()
+  }) };
+}
+
+function consumeDelegation(receipt: DelegationReceipt, options: { now?: () => string } = {}): ReceiptResult {
+  if (receipt.status === 'consumed') return fail('DELEGATION_REPLAY', `delegation ${receipt.id} was already consumed`);
+  if (receipt.status !== 'sealed') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected sealed`);
+  return { ok: true, receipt: Object.freeze({
+    ...receipt,
+    status: 'consumed',
+    consumedAt: (options.now ?? (() => new Date().toISOString()))()
+  }) };
+}
+
+export {
+  activateDelegation,
+  completeDelegationStage,
+  consumeDelegation,
+  managedDelegationRole,
+  prepareDelegation,
+  sealDelegation
+};
+export type { DelegationReceipt, DelegationRole, DelegationStage, DelegationStatus, ReceiptResult };

package/lib/task/events.ts

@@ -16,8 +16,12 @@ import {
   parseImplementationInputs,
   renderImplementationInputs
 } from './implementation-inputs.ts';
+import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import type { ReviewStage } from './ledger.ts';
+import { parseReviewSummary } from './review-artifacts.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { findSectionHeading } from './sections.ts';
+import { completeOrchestrationStage, validateOrchestrationStage } from './orchestration.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskOperationSummary, TaskWriteErrorCode, TaskWriteOptions } from './write.ts';
 
@@ -35,7 +39,8 @@ type Verdict = 'approved' | 'changes-requested' | 'rejected';
 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' | ArtifactErrorCode | TaskWriteErrorCode;
+  | 'EVENT_LOG_CONFLICT' | 'EVENT_ARTIFACT_CONFLICT' | 'EVENT_FINDING_COUNT_MISMATCH'
+  | ArtifactErrorCode | TaskWriteErrorCode;
 type TaskEventRequest = {
   taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean;
   round?: number; question?: number; artifact?: string; fixFor?: string; implementationInput?: string;
@@ -105,7 +110,7 @@ function validateTaskEventRequest(request: TaskEventRequest): TaskEventError | n
 const FAMILY = {
   analyze: { artifact: 'analysis', started: ['requirement-analysis', 'requirement-analysis-review', 'code'], completed: ['requirement-analysis', 'requirement-analysis-review', 'code'], target: 'requirement-analysis', label: 'Analyze Task' },
   'review-analysis': { artifact: 'review-analysis', started: ['requirement-analysis', 'requirement-analysis-review'], completed: ['requirement-analysis', 'requirement-analysis-review'], target: 'requirement-analysis-review', label: 'Review Analysis' },
-  plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review'], completed: ['requirement-analysis-review', 'technical-design-review'], target: 'technical-design', label: 'Plan Task' },
+  plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review', 'commit'], completed: ['requirement-analysis-review', 'technical-design-review', 'commit'], target: 'technical-design', label: 'Plan Task' },
   'review-plan': { artifact: 'review-plan', started: ['technical-design', 'technical-design-review'], completed: ['technical-design', 'technical-design-review'], target: 'technical-design-review', label: 'Review Plan' },
   code: { artifact: 'code', started: ['technical-design-review', 'code-review'], completed: ['technical-design-review', 'code-review'], target: 'code', label: 'Code Task' },
   'review-code': { artifact: 'review-code', started: ['code', 'code-review', 'commit'], completed: ['code', 'code-review', 'commit'], target: 'code-review', label: 'Review Code' },
@@ -113,6 +118,72 @@ const FAMILY = {
 } as const;
 type EventFamily = keyof typeof FAMILY;
 
+const REVIEW_LEDGER_STAGES: Partial<Record<EventFamily, ReviewStage>> = {
+  'review-analysis': 'analysis',
+  'review-plan': 'plan',
+  'review-code': 'code'
+};
+
+function validateReviewFindingCounts(
+  request: TaskEventRequest,
+  content: string,
+  family: EventFamily,
+  artifactPath: string | null
+): TaskEventError | null {
+  const stage = REVIEW_LEDGER_STAGES[family];
+  if (!stage || !artifactPath) return null;
+  const rows = parseLedger(content);
+  const invalid = validateLedgerRows(rows);
+  if (invalid) return { code: 'TASK_DOCUMENT_INVALID', message: `${invalid.code}: ${invalid.message}` };
+  const expected = summarizeLedgerStage(rows, stage).unresolvedFindingCounts;
+  const payload = {
+    blocker: request.blockers!,
+    major: request.major!,
+    minor: request.minor!
+  };
+  let reportContent: string;
+  try {
+    reportContent = fs.readFileSync(artifactPath, 'utf8');
+  } catch (error) {
+    return { code: 'EVENT_FINDING_COUNT_MISMATCH', message: String(error) };
+  }
+  const parsed = parseReviewSummary(reportContent);
+  if (!parsed.ok || !parsed.summary.counts) {
+    return {
+      code: 'EVENT_FINDING_COUNT_MISMATCH',
+      message: parsed.ok ? 'review summary finding counts are not finalized' : parsed.message
+    };
+  }
+  const report = parsed.summary.counts;
+  const reportVerdict = parsed.summary.verdict === 'Approved'
+    ? 'approved'
+    : parsed.summary.verdict === 'Changes Requested' ? 'changes-requested' : 'rejected';
+  const fields = [
+    ['blocker', 'blockers'],
+    ['major', 'major'],
+    ['minor', 'minor']
+  ] as const;
+  const differences = fields.flatMap(([severity, cliField]) => {
+    const values = [
+      expected[severity] === payload[severity]
+        ? null
+        : `${cliField} ledger ${expected[severity]}, payload ${payload[severity]}`,
+      expected[severity] === report[severity]
+        ? null
+        : `${cliField} ledger ${expected[severity]}, report ${report[severity]}`
+    ];
+    return values.filter((value): value is string => value !== null);
+  });
+  if (request.verdict !== reportVerdict) {
+    differences.push(`verdict report ${reportVerdict}, payload ${request.verdict}`);
+  }
+  if (differences.length === 0) return null;
+  return {
+    code: 'EVENT_FINDING_COUNT_MISMATCH',
+    message: `review summary, payload, and ${stage} ledger do not match: ${differences.join('; ')}`
+  };
+}
+
 function eventParts(event: string): { family: EventFamily; phase: 'started' | 'waiting' | 'completed' } {
   const [family, suffix] = event.split('.') as [EventFamily, string];
   return { family, phase: suffix === 'started' ? 'started' : suffix === 'awaiting-input' ? 'waiting' : 'completed' };
@@ -256,6 +327,28 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {
   }
   const allowed = FAMILY[eventIdentity.family][eventIdentity.phase === 'started' ? 'started' : 'completed'];
   if (!(allowed as readonly string[]).includes(currentStep)) return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${normalized.event} is not allowed from '${currentStep}'` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  const findingCountError = validateReviewFindingCounts(
+    normalized,
+    content,
+    eventIdentity.family,
+    completedArtifact?.path ?? null
+  );
+  if (findingCountError) return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  if (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
+    const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
+    const provenance = validateOrchestrationStage(normalized.taskRef, {
+      stage: orchestrationStage,
+      round: normalized.round!,
+      artifact: normalized.artifact!,
+      role: eventIdentity.family.startsWith('review-') ? 'reviewer' : 'executor'
+    }, { repoRoot: options.repoRoot });
+    if (provenance.status === 'failed' || provenance.status === 'paused') {
+      return failed(normalized, {
+        code: 'EVENT_TRANSITION_INVALID',
+        message: provenance.error?.message ?? provenance.run?.pause?.message ?? 'orchestration provenance validation failed'
+      }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    }
+  }
   let metadata;
   try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
   catch (error) { return failed(normalized, { code: 'METADATA_CAPTURE_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
@@ -291,6 +384,21 @@ function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {
   mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body });
   const result = writeTask({ taskRef: normalized.taskRef, expectedState: 'active', dryRun: normalized.dryRun, mutations }, { ...options, metadataProvider: () => metadata });
   if (result.status === 'failed') return failed(normalized, result.error, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+  if (eventIdentity.phase === 'completed' && !normalized.dryRun && eventIdentity.family !== 'manual-validation') {
+    const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
+    const orchestration = completeOrchestrationStage(normalized.taskRef, {
+      stage: orchestrationStage,
+      round: normalized.round!,
+      artifact: normalized.artifact!,
+      agent: normalized.agent
+    }, { repoRoot: options.repoRoot });
+    if (orchestration.status === 'failed' || orchestration.status === 'paused') {
+      return failed(normalized, {
+        code: 'EVENT_TRANSITION_INVALID',
+        message: orchestration.error?.message ?? orchestration.run?.pause?.message ?? 'orchestration provenance validation failed'
+      }, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
+    }
+  }
   return {
     status: result.status, changed: result.changed, event: normalized.event,
     requestRef: normalized.taskRef, taskId: result.taskId, taskMdPath: result.taskMdPath,