@fitlab-ai/agent-infra 0.8.5 → 0.9.1

package/lib/task/decision-intents.ts

@@ -0,0 +1,163 @@
+import fs from 'node:fs';
+
+import { appendActivityEntry, locateActivityLog } from './activity-log.ts';
+import { isDecisionItem, listDecisionItems, selectDecisionItem } from './decision-items.ts';
+import {
+  createImplementationInput,
+  IMPLEMENTATION_INPUT_ALIASES,
+  parseImplementationInputs,
+  renderImplementationInputs
+} from './implementation-inputs.ts';
+import { LEDGER_COLUMNS, LEDGER_HEADINGS, parseLedger } from './ledger.ts';
+import type { LedgerRow } from './ledger.ts';
+import { resolveTaskContext } from './resolve-ref.ts';
+import { extractSection, extractSubSection, findSectionHeading } from './sections.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
+
+type HumanDecisionRequest = {
+  taskRef?: string;
+  selector: string;
+  decision: string;
+  needsImplementation?: boolean;
+  dryRun?: boolean;
+};
+
+type HumanDecisionResult = {
+  status: 'planned' | 'applied' | 'no-op' | 'failed'; changed: boolean;
+  taskId: string | null; ledgerId: string | null; recordId: string | null;
+  implementationInputId: string | null; operations: readonly TaskOperationSummary[];
+  error: { code: string; message: string } | null;
+};
+
+const DECISION_ALIASES = ['人工裁决', 'Human Rulings', 'Human Decisions', 'Human Decision'] as const;
+const ACTIVITY_ALIASES = ['活动日志', 'Activity Log'] as const;
+
+function failed(code: string, message: string, taskId: string | null = null, ledgerId: string | null = null): HumanDecisionResult {
+  return { status: 'failed', changed: false, taskId, ledgerId, recordId: null, implementationInputId: null, operations: [], error: { code, message } };
+}
+
+function nextRecordId(content: string): string {
+  let max = 0;
+  for (const match of content.matchAll(/^###\s+HDR-(\d+)\s*$/gm)) max = Math.max(max, Number(match[1]));
+  return `HDR-${max + 1}`;
+}
+
+function classifyMissing(rows: readonly LedgerRow[], selector: string): string {
+  const matches = rows.filter((row) => row.id.toUpperCase() === selector.toUpperCase());
+  const valid = matches.filter(isDecisionItem);
+  if (valid.some((row) => row.status === 'human-decided')) return `${selector} is already decided`;
+  if (valid.length > 0) return `${selector} is not a pending review decision`;
+  if (matches.length > 0 || !/^(AN|PL|CD|HD)-\d+$/i.test(selector)) return `${selector} is an invalid decision item`;
+  return `${selector} not found in review ledger`;
+}
+
+function prependBlock(body: string, block: string): string {
+  return body ? `${block}\n\n${body}` : block;
+}
+
+function existingDecision(
+  content: string,
+  row: LedgerRow,
+  decision: string,
+  needsImplementation: boolean | undefined
+): { recordId: string; implementationInputId: string | null } | { conflict: string } {
+  const match = /^task\.md#(HDR-[1-9]\d*)$/.exec(row.evidence);
+  if (!match) return { conflict: `decided row '${row.id}' has invalid decision evidence` };
+  const recordId = match[1]!;
+  const block = extractSubSection(content, recordId);
+  if (!block || !block.includes(`**原账本 ID**：${row.id}`) || !block.includes(`**裁决结果**：${decision}`)) {
+    return { conflict: `decision for '${row.id}' conflicts with ${recordId}` };
+  }
+  if (row.stage !== 'code') return needsImplementation === undefined
+    ? { recordId, implementationInputId: null }
+    : { conflict: '--needs-implementation is only valid for code-stage decisions' };
+  const inputs = parseImplementationInputs(content).rows.filter((input) => input.ledgerId === row.id && input.decisionEvidence === row.evidence);
+  if (inputs.length !== 1 || inputs[0]!.needsImplementation !== needsImplementation) {
+    return { conflict: `implementation intent for '${row.id}' conflicts with the existing decision` };
+  }
+  return { recordId, implementationInputId: inputs[0]!.id };
+}
+
+function applyHumanDecision(request: HumanDecisionRequest, options: TaskWriteOptions = {}): HumanDecisionResult {
+  if (!request.selector || !request.decision.trim()) return failed('DECISION_PAYLOAD_INVALID', 'selector and decision are required');
+  const resolved = resolveTaskContext(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+  if (resolved.state !== 'active') 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); }
+  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());
+  if (!/^-?\d+$/.test(request.selector) && direct.length === 1 && direct[0]!.status === 'human-decided' && isDecisionItem(direct[0]!)) {
+    try {
+      const replay = existingDecision(content, direct[0]!, request.decision.trim(), request.needsImplementation);
+      if ('conflict' in replay) return failed('DECISION_CONFLICT', replay.conflict, resolved.taskId, direct[0]!.id);
+      return { status: 'no-op', changed: false, taskId: resolved.taskId, ledgerId: direct[0]!.id, recordId: replay.recordId, implementationInputId: replay.implementationInputId, operations: [], error: null };
+    } catch (error) { return failed('DECISION_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId, direct[0]!.id); }
+  }
+
+  const candidates = listDecisionItems(rows);
+  const selected = selectDecisionItem(candidates, request.selector);
+  if (!selected.ok) {
+    const message = selected.code === 'not-found' && !/^-?\d+$/.test(request.selector)
+      ? classifyMissing(rows, request.selector) : selected.message;
+    return failed('DECISION_TARGET_INVALID', message, resolved.taskId);
+  }
+  const row = selected.row;
+  if (row.stage === 'code' && request.needsImplementation === undefined) return failed('DECISION_PAYLOAD_INVALID', 'code-stage decisions require --needs-implementation true|false', resolved.taskId, row.id);
+  if (row.stage !== 'code' && request.needsImplementation !== undefined) return failed('DECISION_PAYLOAD_INVALID', '--needs-implementation is only valid for code-stage decisions', resolved.taskId, row.id);
+
+  let metadata;
+  try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
+  catch (error) { return failed('METADATA_CAPTURE_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId, row.id); }
+  const recordId = nextRecordId(content);
+  const evidence = `task.md#${recordId}`;
+  const decision = request.decision.trim();
+  const record = `### ${recordId}\n\n- **原账本 ID**：${row.id}\n- **裁决时间**：${metadata.timestamp}\n- **裁决结果**：${decision}`;
+  const activity = locateActivityLog(content);
+  if (!activity) return failed('DECISION_ACTIVITY_MISSING', 'activity log section is missing or ambiguous', resolved.taskId, row.id);
+  const mutations: TaskMutation[] = [
+    {
+      kind: 'table-row', action: 'upsert', sectionAliases: LEDGER_HEADINGS, columns: LEDGER_COLUMNS,
+      keyColumn: 'id', key: row.id,
+      values: { stage: row.stage, round: row.round, severity: row.severity, status: 'human-decided', evidence }
+    },
+    {
+      kind: 'section', aliases: DECISION_ALIASES,
+      heading: findSectionHeading(content, [...DECISION_ALIASES]),
+      body: prependBlock(extractSection(content, [...DECISION_ALIASES]), record)
+    }
+  ];
+  let implementationInputId: string | null = null;
+  if (row.stage === 'code') {
+    let parsed;
+    try { parsed = parseImplementationInputs(content); }
+    catch (error) { return failed('DECISION_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId, row.id); }
+    const input = createImplementationInput(parsed.rows, {
+      ledgerId: row.id, decisionEvidence: evidence,
+      needsImplementation: request.needsImplementation!, decidedAt: metadata.timestamp
+    });
+    implementationInputId = input.id;
+    mutations.push({
+      kind: 'section', aliases: IMPLEMENTATION_INPUT_ALIASES,
+      heading: findSectionHeading(content, [...IMPLEMENTATION_INPUT_ALIASES]),
+      body: renderImplementationInputs([...parsed.rows, input])
+    });
+  }
+  mutations.push({
+    kind: 'section', aliases: ACTIVITY_ALIASES, heading: activity.heading,
+    body: appendActivityEntry(activity, { time: metadata.timestamp, step: 'Human Decision', agent: 'human', note: `${row.id} decided → ${recordId}` })
+  });
+  const writeResult = writeTask({ taskRef: resolved.taskId, expectedState: 'active', mutations, dryRun: request.dryRun }, {
+    ...options,
+    taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state },
+    metadataProvider: () => metadata
+  });
+  if (writeResult.status === 'failed') return failed(writeResult.error.code, writeResult.error.message, writeResult.taskId, row.id);
+  return { status: writeResult.status, changed: writeResult.changed, taskId: writeResult.taskId, ledgerId: row.id, recordId, implementationInputId, operations: writeResult.operations, error: null };
+}
+
+export { applyHumanDecision };
+export type { HumanDecisionRequest, HumanDecisionResult };

package/lib/task/decision-items.ts

@@ -0,0 +1,64 @@
+import { isReviewStage, type LedgerRow, type ReviewStage } from './ledger.ts';
+
+type DecisionSelectorErrorCode =
+  | 'invalid-selector'
+  | 'not-found'
+  | 'ambiguous'
+  | 'ordinal-out-of-range';
+
+type DecisionSelectorResult =
+  | { ok: true; row: LedgerRow }
+  | { ok: false; code: DecisionSelectorErrorCode; message: string };
+
+function isDecisionItem(row: LedgerRow): boolean {
+  if (!isReviewStage(row.stage)) return false;
+  if (/^HD-\d+$/i.test(row.id)) return true;
+  if (row.stage === 'analysis') return /^AN-\d+$/i.test(row.id);
+  if (row.stage === 'plan') return /^PL-\d+$/i.test(row.id);
+  return /^CD-\d+$/i.test(row.id);
+}
+
+function listDecisionItems(
+  rows: readonly LedgerRow[],
+  options: { includeDecided?: boolean; stage?: ReviewStage } = {}
+): LedgerRow[] {
+  return rows.filter((row) => {
+    if (!isDecisionItem(row)) return false;
+    if (options.stage !== undefined && row.stage !== options.stage) return false;
+    return options.includeDecided
+      ? row.status === 'needs-human-decision' || row.status === 'human-decided'
+      : row.status === 'needs-human-decision';
+  });
+}
+
+function selectDecisionItem(rows: readonly LedgerRow[], selector: string): DecisionSelectorResult {
+  if (/^-?\d+$/.test(selector)) {
+    const ordinal = Number.parseInt(selector, 10);
+    if (ordinal < 1 || ordinal > rows.length) {
+      return {
+        ok: false,
+        code: 'ordinal-out-of-range',
+        message: `ordinal '${selector}' out of range (1..${rows.length})`
+      };
+    }
+    return { ok: true, row: rows[ordinal - 1]! };
+  }
+  if (!/^[A-Za-z]+-\d+$/.test(selector)) {
+    return { ok: false, code: 'invalid-selector', message: `invalid selector '${selector}'` };
+  }
+  const matches = rows.filter((row) => row.id.toUpperCase() === selector.toUpperCase());
+  if (matches.length === 0) {
+    return { ok: false, code: 'not-found', message: `no decision item matches '${selector}'` };
+  }
+  if (matches.length > 1) {
+    return {
+      ok: false,
+      code: 'ambiguous',
+      message: `duplicate id '${selector}' in ledger; select by ordinal instead`
+    };
+  }
+  return { ok: true, row: matches[0]! };
+}
+
+export { isDecisionItem, listDecisionItems, selectDecisionItem };
+export type { DecisionSelectorErrorCode, DecisionSelectorResult };

package/lib/task/events.ts

@@ -0,0 +1,320 @@
+import fs from 'node:fs';
+
+import { appendActivityEntry, locateActivityLog, pairEntries } from './activity-log.ts';
+import {
+  buildArtifactLinkSection,
+  artifactName,
+  parseArtifactName,
+  resolveArtifactContext,
+  validateCompletedArtifact
+} from './artifact-lifecycle.ts';
+import type { ArtifactContextResult, ArtifactErrorCode, ArtifactFamily, ArtifactIdentity } from './artifact-lifecycle.ts';
+import { parseTypedTaskFrontmatter } from './frontmatter.ts';
+import {
+  consumeImplementationInput,
+  IMPLEMENTATION_INPUT_ALIASES,
+  parseImplementationInputs,
+  renderImplementationInputs
+} from './implementation-inputs.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { findSectionHeading } from './sections.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import type { TaskOperationSummary, TaskWriteErrorCode, TaskWriteOptions } from './write.ts';
+
+const eventCatalog = [
+  'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
+  'review-analysis.started', 'review-analysis.completed',
+  'plan.started', 'plan.completed',
+  'review-plan.started', 'review-plan.completed',
+  'code.started', 'code.completed',
+  'review-code.started', 'review-code.completed',
+  'manual-validation.started', 'manual-validation.completed'
+] as const;
+type TaskEventName = (typeof eventCatalog)[number];
+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;
+type TaskEventRequest = {
+  taskRef: string; event: TaskEventName | string; agent: string; dryRun?: boolean;
+  round?: number; question?: number; artifact?: string; fixFor?: string; implementationInput?: string;
+  verdict?: Verdict; blockers?: number; major?: number; minor?: number;
+  manualValidation?: number; filesModified?: number; testsPassed?: number;
+  summaryResult?: string;
+};
+type TaskEventError = { code: TaskEventErrorCode; message: string };
+type TaskEventResult = {
+  status: 'planned' | 'applied' | 'no-op' | 'failed'; changed: boolean;
+  event: string; requestRef: string; taskId: string | null; taskMdPath: string | null;
+  fromStep: string | null; toStep: string | null; action: string | null;
+  phase: 'started' | 'waiting' | 'completed' | null; round: number | null;
+  artifact: string | null; fixFor: string | null; implementationInput: string | null;
+  artifactContext: ArtifactContextResult | null;
+  timestamp: string | null; agentInfraVersion: string | null;
+  operations: readonly TaskOperationSummary[]; error: TaskEventError | null;
+};
+
+const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun']);
+const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[] }> = {
+  'analyze.started': { optional: ['round'] },
+  'analyze.awaiting-input': { required: ['question'] },
+  'analyze.completed': { required: ['artifact'], optional: ['round'] },
+  'review-analysis.started': { optional: ['round'] },
+  'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+  'plan.started': { optional: ['round'] },
+  'plan.completed': { required: ['artifact'], optional: ['round'] },
+  'review-plan.started': { optional: ['round'] },
+  'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+  'code.started': { optional: ['round', 'fixFor', 'implementationInput'] },
+  'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation'] },
+  'review-code.started': { optional: ['round'] },
+  'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round'] },
+  'manual-validation.started': { optional: ['round'] },
+  'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] }
+};
+
+function validateTaskEventRequest(request: TaskEventRequest): TaskEventError | null {
+  if (!eventCatalog.includes(request.event as TaskEventName)) return { code: 'EVENT_UNKNOWN', message: `unknown task event '${request.event}'` };
+  if (!request.taskRef || !request.agent) return { code: 'EVENT_PAYLOAD_INVALID', message: 'taskRef and agent are required' };
+  const schema = SCHEMAS[request.event as TaskEventName];
+  const required = schema.required ?? [];
+  const allowed = new Set([...BASE_FIELDS, ...required, ...(schema.optional ?? [])]);
+  for (const [key, value] of Object.entries(request)) {
+    if (value !== undefined && !allowed.has(key)) return { code: 'EVENT_PAYLOAD_INVALID', message: `${request.event} does not accept '${key}'` };
+  }
+  for (const key of required) if (request[key as keyof TaskEventRequest] === undefined) return { code: 'EVENT_PAYLOAD_INVALID', message: `${request.event} requires '${key}'` };
+  for (const key of ['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed'] as const) {
+    const value = request[key];
+    if (value !== undefined && (!Number.isInteger(value) || value < (key === 'round' || key === 'question' ? 1 : 0))) return { code: 'EVENT_PAYLOAD_INVALID', message: `'${key}' must be a ${key === 'round' || key === 'question' ? 'positive' : 'non-negative'} integer` };
+  }
+  if (request.verdict && !['approved', 'changes-requested', 'rejected'].includes(request.verdict)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'verdict is invalid' };
+  if (request.event === 'code.completed') {
+    const fix = request.fixFor !== undefined || ['blockers', 'major', 'minor', 'manualValidation'].some((key) => request[key as keyof TaskEventRequest] !== undefined);
+    const modeRequired = fix ? ['fixFor', 'blockers', 'major', 'minor', 'manualValidation'] : ['filesModified', 'testsPassed'];
+    const forbidden = fix ? ['filesModified', 'testsPassed'] : ['fixFor', 'blockers', 'major', 'minor', 'manualValidation'];
+    if (modeRequired.some((key) => request[key as keyof TaskEventRequest] === undefined) || forbidden.some((key) => request[key as keyof TaskEventRequest] !== undefined)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'code.completed requires either initial or fix completion payload' };
+  }
+  if (request.fixFor && !/^review-code(?:-r(?:[2-9]|[1-9]\d+))?\.md$/.test(request.fixFor)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor must reference a canonical review-code artifact' };
+  if (request.implementationInput && !/^II-[1-9]\d*$/.test(request.implementationInput)) return { code: 'EVENT_PAYLOAD_INVALID', message: 'implementationInput must be a canonical II-N id' };
+  if (request.fixFor && request.implementationInput) return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor and implementationInput are mutually exclusive' };
+  if (request.summaryResult !== undefined && (!request.summaryResult.trim() || /[\r\n]/.test(request.summaryResult))) return { code: 'EVENT_PAYLOAD_INVALID', message: 'summaryResult must be a non-empty single line' };
+  return null;
+}
+
+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' },
+  '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' },
+  'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' }
+} as const;
+type EventFamily = keyof typeof FAMILY;
+
+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' };
+}
+
+function identity(request: TaskEventRequest) {
+  const { family, phase } = eventParts(request.event);
+  if (phase === 'waiting') return { family, phase, action: 'Analyze Task (Brainstorming)', note: `Asked Q${request.question}, awaiting answer`, target: FAMILY.analyze.target } as const;
+  const spec = FAMILY[family];
+  if (family === 'manual-validation') {
+    return {
+      family, phase, action: spec.label,
+      note: phase === 'started' ? 'started' : `Manual validation passed → ${request.artifact}; ${request.summaryResult}`,
+      target: null
+    } as const;
+  }
+  const qualifier = request.fixFor
+    ? `, fix for ${request.fixFor}`
+    : request.implementationInput ? `, decision ${request.implementationInput}` : '';
+  const action = `${spec.label} (Round ${request.round}${qualifier})`;
+  if (phase === 'started') return { family, phase, action, note: 'started', target: null } as const;
+  let note = '';
+  if (family === 'analyze') note = `Analysis completed → ${request.artifact}`;
+  else if (family === 'plan') note = `Plan completed, awaiting human review → ${request.artifact}`;
+  else if (family === 'code' && request.fixFor) note = `Fixed ${request.blockers} blockers, ${request.major} major, ${request.minor} minor issues${request.manualValidation ? `, skipped ${request.manualValidation} manual-validation` : ''} → ${request.artifact}`;
+  else if (family === 'code') note = `Code implemented, ${request.filesModified} files modified, ${request.testsPassed} tests passed → ${request.artifact}`;
+  else {
+    const verdict = request.verdict === 'approved' ? 'Approved' : request.verdict === 'changes-requested' ? 'Changes Requested' : 'Rejected';
+    note = `Verdict: ${verdict}, blockers: ${request.blockers}, major: ${request.major}, minor: ${request.minor}, Manual-validation: ${request.manualValidation} → ${request.artifact}`;
+  }
+  return { family, phase, action, note, target: spec.target } as const;
+}
+
+function failed(request: TaskEventRequest, error: TaskEventError, extra: Partial<TaskEventResult> = {}): TaskEventResult {
+  return {
+    status: 'failed', changed: false, event: request.event, requestRef: request.taskRef,
+    taskId: null, taskMdPath: null, fromStep: null, toStep: null, action: null,
+    phase: null, round: request.round ?? null, artifact: request.artifact ?? null,
+    fixFor: request.fixFor ?? null, implementationInput: request.implementationInput ?? null,
+    artifactContext: null, timestamp: null,
+    agentInfraVersion: null, operations: [], error, ...extra
+  };
+}
+
+function normalizeStarted(request: TaskEventRequest, repoRoot: string): { request: TaskEventRequest; context: ArtifactContextResult } | { error: TaskEventError; context: ArtifactContextResult } {
+  const family = eventParts(request.event).family;
+  const context = resolveArtifactContext(request.taskRef, FAMILY[family].artifact, { repoRoot });
+  if (context.status !== 'ready' || !context.next) {
+    return { error: { code: context.error?.code ?? 'EVENT_ARTIFACT_CONFLICT', message: context.error?.message ?? context.codeMode?.message ?? 'artifact context is not writable' }, context };
+  }
+  const round = context.next.round;
+  if (request.round !== undefined && request.round !== round) return { error: { code: 'EVENT_ARTIFACT_CONFLICT', message: `round ${request.round} conflicts with expected round ${round}` }, context };
+  const expectedFix = family === 'code' && context.codeMode?.mode === 'fix' ? context.codeMode.reviewArtifact ?? undefined : undefined;
+  const expectedImplementation = family === 'code' && context.codeMode?.mode === 'decision'
+    ? context.codeMode.implementationInput ?? undefined : undefined;
+  if (request.fixFor !== undefined && request.fixFor !== expectedFix) return { error: { code: 'EVENT_ARTIFACT_CONFLICT', message: `fixFor '${request.fixFor}' conflicts with artifact context` }, context };
+  if (request.implementationInput !== expectedImplementation) return { error: { code: 'EVENT_ARTIFACT_CONFLICT', message: `implementationInput '${request.implementationInput ?? ''}' conflicts with artifact context` }, context };
+  return { request: { ...request, round, artifact: context.next.name, fixFor: expectedFix, implementationInput: expectedImplementation }, context };
+}
+
+function openStartedIdentity(rows: ReturnType<typeof pairEntries>, family: EventFamily) {
+  const spec = FAMILY[family];
+  if (family === 'manual-validation') {
+    const row = rows.filter((item) => item.step === spec.label && item.started && !item.done).at(-1);
+    const completed = rows.filter((item) => item.step === spec.label && item.done).length;
+    return row ? { row, round: completed + 1, fixFor: undefined, implementationInput: undefined } : null;
+  }
+  const escaped = spec.label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`^${escaped} \\(Round (\\d+)(?:(?:, fix for (review-code(?:-r\\d+)?\\.md))|(?:, decision (II-[1-9]\\d*)))?\\)$`);
+  const matches = rows.flatMap((row) => {
+    if (!row.started || row.done) return [];
+    const match = pattern.exec(row.step);
+    return match ? [{ row, round: Number(match[1]), fixFor: match[2], implementationInput: match[3] }] : [];
+  });
+  return matches.length === 1 ? matches[0] : matches.length > 1 ? { conflict: true as const } : null;
+}
+
+function applyTaskEvent(request: TaskEventRequest, options: TaskWriteOptions = {}): TaskEventResult {
+  const invalid = validateTaskEventRequest(request);
+  if (invalid) return failed(request, invalid);
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(request, { code: resolved.code, message: resolved.message }, { taskId: resolved.taskId });
+  if (resolved.state !== 'active') return failed(request, { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected active` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+  let content: string;
+  try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
+  catch (error) { return failed(request, { code: 'TASK_READ_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
+  let frontmatter;
+  try { frontmatter = parseTypedTaskFrontmatter(content); }
+  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);
+  let normalized = request;
+  let artifactContext: ArtifactContextResult | null = null;
+  const initialParts = eventParts(request.event);
+  if (initialParts.phase === 'started') {
+    const openIdentity = openStartedIdentity(rows, initialParts.family);
+    if (openIdentity && 'conflict' in openIdentity) return failed(request, { code: 'EVENT_LOG_CONFLICT', message: 'artifact family has more than one open started event' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    if (openIdentity) {
+      if (openIdentity.row.agent !== request.agent) return failed(request, { code: 'EVENT_LOG_CONFLICT', message: 'open started event has a different agent' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+      if (request.round !== undefined && request.round !== openIdentity.round) return failed(request, { code: 'EVENT_ARTIFACT_CONFLICT', message: `round ${request.round} conflicts with open round ${openIdentity.round}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+      if (request.fixFor !== undefined && request.fixFor !== openIdentity.fixFor) return failed(request, { code: 'EVENT_ARTIFACT_CONFLICT', message: `fixFor '${request.fixFor}' conflicts with open event` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+      if (request.implementationInput !== openIdentity.implementationInput) return failed(request, { code: 'EVENT_ARTIFACT_CONFLICT', message: `implementationInput '${request.implementationInput ?? ''}' conflicts with open event` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+      normalized = { ...request, round: openIdentity.round, artifact: artifactName(FAMILY[initialParts.family].artifact, openIdentity.round), fixFor: openIdentity.fixFor, implementationInput: openIdentity.implementationInput };
+      return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, typeof frontmatter.current_step === 'string' ? frontmatter.current_step : '', identity(normalized), openIdentity.row.started, frontmatter, null);
+    }
+    const result = normalizeStarted(request, resolved.repoRoot);
+    artifactContext = result.context;
+    if ('error' in result) return failed(request, result.error, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, artifactContext });
+    normalized = result.request;
+  } else if (initialParts.phase === 'completed') {
+    const identity = request.artifact ? parseArtifactName(request.artifact) : null;
+    if (identity?.family === FAMILY[initialParts.family].artifact) normalized = { ...request, round: identity.round };
+  }
+  const eventIdentity = identity(normalized);
+  const currentStep = typeof frontmatter.current_step === 'string' ? frontmatter.current_step : '';
+  const matchingRows = rows.filter((item) => item.step === eventIdentity.action);
+  const manual = eventIdentity.family === 'manual-validation';
+  if (!manual && matchingRows.length > 1) return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'event identity appears more than once' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+  const openRows = matchingRows.filter((item) => item.started && !item.done);
+  const completedRows = matchingRows.filter((item) => item.done);
+  const row = manual ? openRows.at(-1) : matchingRows[0];
+  let completedArtifact: ArtifactIdentity | null = null;
+  if (eventIdentity.phase === 'started' && row) {
+    if (row.agent !== normalized.agent) return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'open started event has a different agent' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+    return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, row.started, frontmatter, artifactContext);
+  }
+  if (eventIdentity.phase === 'started' && !manual && completedRows.length > 0) return failed(normalized, { code: 'EVENT_ALREADY_COMPLETED', message: 'event identity is already completed' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+  const done = completedRows.find((item) => item.note === eventIdentity.note);
+  if (eventIdentity.phase === 'completed' && done) return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, done.done, frontmatter, artifactContext);
+  if (eventIdentity.phase === 'completed' && completedRows.length > 0 && openRows.length === 0) return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'event identity is already completed with a different payload' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  if (eventIdentity.phase === 'completed' && !row?.started) return failed(normalized, { code: 'EVENT_START_MISSING', message: 'completion requires one open matching started event' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+  if (eventIdentity.phase === 'completed') {
+    const validated = validateCompletedArtifact(resolved.taskDir, FAMILY[eventIdentity.family].artifact, normalized.artifact!, normalized.round);
+    if (!validated.ok) return failed(normalized, validated.error, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    completedArtifact = validated.artifact;
+  }
+  if (eventIdentity.phase === 'waiting' && section.entries.some((entry) => entry.step === eventIdentity.action && entry.note === eventIdentity.note)) {
+    const existing = section.entries.find((entry) => entry.step === eventIdentity.action && entry.note === eventIdentity.note)!;
+    return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, existing.time, frontmatter, artifactContext);
+  }
+  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 });
+  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 }); }
+  const step = eventIdentity.phase === 'started' || eventIdentity.target === null ? currentStep : eventIdentity.target;
+  const logStep = eventIdentity.phase === 'started' ? `${eventIdentity.action} [started]` : eventIdentity.action;
+  const body = appendActivityEntry(section, { time: metadata.timestamp, step: logStep, agent: normalized.agent, note: eventIdentity.note });
+  const frontmatterSet: Record<string, string> = { current_step: step, assigned_to: normalized.agent };
+  if (eventIdentity.phase === 'started' && normalized.implementationInput) frontmatterSet.last_reviewed_commit = '';
+  const mutations: Parameters<typeof writeTask>[0]['mutations'][number][] = [
+    { kind: 'frontmatter', set: frontmatterSet }
+  ];
+  if (completedArtifact) {
+    const link = buildArtifactLinkSection(content, completedArtifact);
+    mutations.push({ kind: 'section', aliases: link.aliases, heading: link.heading, body: link.body });
+  }
+  if (eventIdentity.phase === 'completed' && normalized.implementationInput) {
+    let implementationRows;
+    try {
+      implementationRows = consumeImplementationInput(
+        parseImplementationInputs(content).rows,
+        normalized.implementationInput,
+        normalized.artifact!
+      );
+    } catch (error) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: error instanceof Error ? error.message : String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
+    mutations.push({
+      kind: 'section', aliases: IMPLEMENTATION_INPUT_ALIASES,
+      heading: findSectionHeading(content, [...IMPLEMENTATION_INPUT_ALIASES]),
+      body: renderImplementationInputs(implementationRows)
+    });
+  }
+  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 });
+  return {
+    status: result.status, changed: result.changed, event: normalized.event,
+    requestRef: normalized.taskRef, taskId: result.taskId, taskMdPath: result.taskMdPath,
+    fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase,
+    round: normalized.round ?? null, artifact: normalized.artifact ?? null,
+    fixFor: normalized.fixFor ?? null, implementationInput: normalized.implementationInput ?? null,
+    artifactContext, timestamp: result.timestamp,
+    agentInfraVersion: result.agentInfraVersion, operations: result.operations, error: null
+  };
+}
+
+function successNoOp(
+  request: TaskEventRequest, taskId: string, taskMdPath: string, currentStep: string,
+  eventIdentity: ReturnType<typeof identity>, timestamp: string,
+  frontmatter: Record<string, unknown>, artifactContext: ArtifactContextResult | null
+): TaskEventResult {
+  return {
+    ...failed(request, { code: 'EVENT_LOG_CONFLICT', message: '' }), status: 'no-op', error: null,
+    taskId, taskMdPath, fromStep: currentStep, toStep: currentStep,
+    action: eventIdentity.action, phase: eventIdentity.phase, timestamp,
+    agentInfraVersion: typeof frontmatter.agent_infra_version === 'string' ? frontmatter.agent_infra_version : null,
+    artifactContext
+  };
+}
+
+export { eventCatalog, validateTaskEventRequest, applyTaskEvent };
+export type { TaskEventName, TaskEventRequest, TaskEventResult, TaskEventError, TaskEventErrorCode, Verdict };