@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/lib/task/review-artifacts.ts

@@ -1,116 +1,248 @@
-// Shared helpers for review-artifact parsing.
-// Imported by typed artifact lifecycle and verification so the round/verdict vocabulary stays
-// in a single source of truth (prevents the cross-file drift this lifecycle
-// is designed to eliminate).
-import fs from "node:fs";
-import path from "node:path";
-
-export function escapeRegExp(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+import fs from 'node:fs';
+import path from 'node:path';
+
+type ReviewFindingCounts = {
+  blocker: number;
+  major: number;
+  minor: number;
+};
+
+type ReviewVerdict = 'Approved' | 'Changes Requested' | 'Rejected';
+type ReviewSummary = {
+  verdict: ReviewVerdict;
+  counts: ReviewFindingCounts | null;
+  manualValidation: number | null;
+  countState: 'placeholders' | 'numeric';
+};
+type ReviewSummaryErrorCode =
+  | 'REVIEW_SUMMARY_NOT_FOUND'
+  | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
+  | 'REVIEW_SUMMARY_COUNT_MISMATCH';
+type ReviewSummaryParseResult =
+  | { ok: true; summary: ReviewSummary; findingsStart: number; findingsEnd: number }
+  | { ok: false; code: ReviewSummaryErrorCode; message: string };
+type ReviewSummaryFinalizeResult =
+  | { ok: true; changed: boolean; content: string }
+  | { ok: false; code: ReviewSummaryErrorCode; message: string };
+
+const SUMMARY_HEADINGS = new Set(['审查摘要', 'Review Summary']);
+const PLACEHOLDERS = [
+  '{unresolved-blockers}',
+  '{unresolved-major}',
+  '{unresolved-minor}'
+] as const;
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-export function maxRound(entries: string[], stem: string): number {
+function maxRound(entries: string[], stem: string): number {
   let max = 0;
   for (const entry of entries) {
     if (entry === `${stem}.md`) {
       max = Math.max(max, 1);
       continue;
     }
-
     const match = entry.match(new RegExp(`^${escapeRegExp(stem)}-r(\\d+)\\.md$`));
-    if (match) {
-      max = Math.max(max, Number(match[1]));
-    }
+    if (match) max = Math.max(max, Number(match[1]));
   }
   return max;
 }
 
-export function artifactName(stem: string, round: number): string {
+function artifactName(stem: string, round: number): string {
   return round === 1 ? `${stem}.md` : `${stem}-r${round}.md`;
 }
 
-export function normalizeVerdict(raw: unknown): "Approved" | "Changes Requested" | "Rejected" | "" {
+function normalizeVerdict(raw: unknown): ReviewVerdict | '' {
   const value = String(raw).trim().toLowerCase();
-  if (value === "通过" || value === "approved") {
-    return "Approved";
-  }
-  if (value === "需要修改" || value === "changes requested") {
-    return "Changes Requested";
-  }
-  if (value === "拒绝" || value === "rejected") {
-    return "Rejected";
-  }
-  return "";
+  if (value === '通过' || value === 'approved') return 'Approved';
+  if (value === '需要修改' || value === 'changes requested') return 'Changes Requested';
+  if (value === '拒绝' || value === 'rejected') return 'Rejected';
+  return '';
 }
 
-export function extractSection(content: string, names: string[]): string {
+function extractSection(content: string, names: string[]): string {
   const lines = content.split(/\r?\n/);
   const nameSet = new Set(names);
   const start = lines.findIndex((line) => {
     const match = line.trim().match(/^##\s+(.+?)\s*$/);
     return match ? nameSet.has(match[1]!) : false;
   });
-
-  if (start === -1) {
-    return "";
-  }
-
+  if (start === -1) return '';
   const sectionLines = [];
   for (let index = start + 1; index < lines.length; index += 1) {
-    if (/^##\s+/.test(lines[index]!)) {
-      break;
-    }
+    if (/^##\s+/.test(lines[index]!)) break;
     sectionLines.push(lines[index]);
   }
-  return sectionLines.join("\n");
+  return sectionLines.join('\n');
 }
 
-// Parse the canonical verdict out of a review-* artifact.
-// Returns { ok, verdict, message }. Verdict collapses Approved into
-// "Approved-with-issues" when the findings counts are non-zero.
-export function parseVerdict(reviewPath: string) {
-  if (!fs.existsSync(reviewPath)) {
-    return { ok: false, verdict: null, message: `Review artifact not found: ${path.basename(reviewPath)}` };
-  }
+function summaryBounds(content: string): { start: number; end: number } | null {
+  const headings = [...content.matchAll(/^##\s+(.+?)\s*$/gm)]
+    .map((match) => ({ index: match.index, end: match.index + match[0].length, name: match[1]! }));
+  const summaries = headings.filter((heading) => SUMMARY_HEADINGS.has(heading.name));
+  if (summaries.length !== 1) return null;
+  const summary = summaries[0]!;
+  const next = headings.find((heading) => heading.index > summary.index);
+  return { start: summary.end, end: next?.index ?? content.length };
+}
 
-  const content = fs.readFileSync(reviewPath, "utf8");
-  const summary = extractSection(content, ["审查摘要", "Review Summary"]);
-  const fileName = path.basename(reviewPath);
-  if (!summary) {
-    return { ok: false, verdict: null, message: `cannot locate review summary section in ${fileName}` };
-  }
+function uniqueLine(
+  content: string,
+  bounds: { start: number; end: number },
+  pattern: RegExp
+): { value: string; start: number; end: number } | null {
+  const section = content.slice(bounds.start, bounds.end);
+  const matches = [...section.matchAll(pattern)];
+  if (matches.length !== 1) return null;
+  const match = matches[0]!;
+  return {
+    value: match[1]!,
+    start: bounds.start + match.index,
+    end: bounds.start + match.index + match[0].length
+  };
+}
+
+function parseCounts(value: string): ReviewFindingCounts | null {
+  const zh = /^(\d+)\s*阻塞项，\s*(\d+)\s*主要，\s*(\d+)\s*次要(?:\s*\/.*)?$/.exec(value);
+  const en = /^(\d+)\s*blockers?,\s*(\d+)\s*majors?,\s*(\d+)\s*minors?(?:\s*\/.*)?$/i.exec(value);
+  const match = zh ?? en;
+  if (!match) return null;
+  const [blocker, major, minor] = match.slice(1, 4).map(Number);
+  if (![blocker, major, minor].every(Number.isSafeInteger)) return null;
+  return { blocker: blocker!, major: major!, minor: minor! };
+}
 
-  const verdictMatch = summary.match(/^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.+?)\s*$/im);
-  if (!verdictMatch) {
-    return { ok: false, verdict: null, message: `cannot parse verdict in ${fileName}` };
+function parseManualValidation(value: string): number | null {
+  const match = /\*\*(?:人工校验|Manual[- ]validation)\*\*[:：]\s*(\d+)/i.exec(value);
+  if (!match) return null;
+  const count = Number(match[1]);
+  return Number.isSafeInteger(count) ? count : null;
+}
+
+function hasCanonicalPlaceholders(value: string): boolean {
+  const zh = /^\{unresolved-blockers\}\s*阻塞项，\s*\{unresolved-major\}\s*主要，\s*\{unresolved-minor\}\s*次要(?:\s*\/.*)?$/.test(value);
+  const en = /^\{unresolved-blockers\}\s*blockers?,\s*\{unresolved-major\}\s*majors?,\s*\{unresolved-minor\}\s*minors?(?:\s*\/.*)?$/i.test(value);
+  return zh || en;
+}
+
+function parseReviewSummary(content: string): ReviewSummaryParseResult {
+  const bounds = summaryBounds(content);
+  if (!bounds) {
+    return { ok: false, code: 'REVIEW_SUMMARY_NOT_FOUND', message: 'review artifact must contain one review summary section' };
+  }
+  const verdictLine = uniqueLine(
+    content,
+    bounds,
+    /^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.+?)\s*$/gim
+  );
+  const findingsLine = uniqueLine(
+    content,
+    bounds,
+    /^[-*]?\s*\*\*(?:发现（AI 可处理）|Findings \(AI-actionable\))\*\*[:：]\s*(.+?)\s*$/gim
+  );
+  const verdict = verdictLine ? normalizeVerdict(verdictLine.value) : '';
+  if (!verdict || !findingsLine) {
+    return { ok: false, code: 'REVIEW_SUMMARY_NOT_FOUND', message: 'review summary verdict or finding count line is missing or repeated' };
   }
 
-  const verdict = normalizeVerdict(verdictMatch[1]);
-  if (!verdict) {
+  const counts = parseCounts(findingsLine.value);
+  if (counts) {
     return {
-      ok: false,
-      verdict: null,
-      message: `unrecognized verdict '${verdictMatch[1]!.trim()}' in ${fileName}`
+      ok: true,
+      summary: { verdict, counts, manualValidation: parseManualValidation(findingsLine.value), countState: 'numeric' },
+      findingsStart: findingsLine.start,
+      findingsEnd: findingsLine.end
     };
   }
-
-  if (verdict !== "Approved") {
-    return { ok: true, verdict };
+  const placeholderOccurrences = PLACEHOLDERS.map((token) => (
+    [...findingsLine.value.matchAll(new RegExp(escapeRegExp(token), 'g'))].length
+  ));
+  if (hasCanonicalPlaceholders(findingsLine.value) && placeholderOccurrences.every((count) => count === 1)) {
+    return {
+      ok: true,
+      summary: { verdict, counts: null, manualValidation: parseManualValidation(findingsLine.value), countState: 'placeholders' },
+      findingsStart: findingsLine.start,
+      findingsEnd: findingsLine.end
+    };
   }
+  return {
+    ok: false,
+    code: 'REVIEW_SUMMARY_PLACEHOLDER_INVALID',
+    message: 'review summary finding counts must be three canonical placeholders or non-negative integers'
+  };
+}
 
-  const findingsMatch = summary.match(/^[-*]?\s*\*\*(?:发现（AI 可处理）|Findings \(AI-actionable\))\*\*[:：]\s*(.+?)\s*$/im);
-  if (!findingsMatch) {
-    return { ok: false, verdict, message: `cannot parse findings count in ${fileName}` };
-  }
+function equalCounts(left: ReviewFindingCounts, right: ReviewFindingCounts): boolean {
+  return left.blocker === right.blocker && left.major === right.major && left.minor === right.minor;
+}
 
-  const counts = findingsMatch[1]!.match(/(\d+)\s*(?:阻塞项|blockers?).*?(\d+)\s*(?:主要|majors?).*?(\d+)\s*(?:次要|minors?)/i);
-  if (!counts) {
-    return { ok: false, verdict, message: `cannot parse findings count in ${fileName}` };
+function finalizeReviewSummaryContent(
+  content: string,
+  counts: ReviewFindingCounts
+): ReviewSummaryFinalizeResult {
+  const parsed = parseReviewSummary(content);
+  if (!parsed.ok) return parsed;
+  if (parsed.summary.countState === 'numeric') {
+    if (equalCounts(parsed.summary.counts!, counts)) return { ok: true, changed: false, content };
+    return {
+      ok: false,
+      code: 'REVIEW_SUMMARY_COUNT_MISMATCH',
+      message: 'review summary finding counts do not match the ledger snapshot'
+    };
   }
+  let line = content.slice(parsed.findingsStart, parsed.findingsEnd);
+  line = line
+    .replace(PLACEHOLDERS[0], String(counts.blocker))
+    .replace(PLACEHOLDERS[1], String(counts.major))
+    .replace(PLACEHOLDERS[2], String(counts.minor));
+  return {
+    ok: true,
+    changed: true,
+    content: content.slice(0, parsed.findingsStart) + line + content.slice(parsed.findingsEnd)
+  };
+}
 
-  const [, blockers, majors, minors] = counts.map(Number);
+function parseVerdict(reviewPath: string):
+  | { ok: true; verdict: 'Approved' | 'Approved-with-issues' | 'Changes Requested' | 'Rejected' }
+  | { ok: false; verdict: null; message: string } {
+  if (!fs.existsSync(reviewPath)) {
+    return { ok: false, verdict: null, message: `Review artifact not found: ${path.basename(reviewPath)}` };
+  }
+  const parsed = parseReviewSummary(fs.readFileSync(reviewPath, 'utf8'));
+  if (!parsed.ok) {
+    return {
+      ok: false,
+      verdict: null,
+      message: `cannot parse review summary in ${path.basename(reviewPath)}: ${parsed.message}`
+    };
+  }
+  const { verdict, counts } = parsed.summary;
+  if (verdict !== 'Approved') return { ok: true, verdict };
   return {
     ok: true,
-    verdict: blockers === 0 && majors === 0 && minors === 0 ? "Approved" : "Approved-with-issues"
+    verdict: counts && equalCounts(counts, { blocker: 0, major: 0, minor: 0 })
+      ? 'Approved'
+      : 'Approved-with-issues'
   };
 }
+
+export {
+  artifactName,
+  equalCounts,
+  escapeRegExp,
+  extractSection,
+  finalizeReviewSummaryContent,
+  maxRound,
+  normalizeVerdict,
+  parseReviewSummary,
+  parseVerdict
+};
+export type {
+  ReviewFindingCounts,
+  ReviewSummary,
+  ReviewSummaryErrorCode,
+  ReviewSummaryFinalizeResult,
+  ReviewSummaryParseResult,
+  ReviewVerdict
+};

package/lib/task/review-finalization.ts

@@ -0,0 +1,306 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { locateActivityLog, pairEntries } from './activity-log.ts';
+import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.ts';
+import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import type { LedgerStageStatus, ReviewStage } from './ledger.ts';
+import { finalizeReviewSummaryContent } from './review-artifacts.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { validateLifecycleExecution } from './lifecycle-execution.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
+import type { ResolveTaskRefErrorCode } from './resolve-ref.ts';
+
+type ReviewFinalizationErrorCode =
+  | ResolveTaskRefErrorCode
+  | 'TASK_STATE_MISMATCH'
+  | 'REVIEW_PAYLOAD_INVALID'
+  | 'REVIEW_STAGE_INVALID'
+  | 'REVIEW_ARTIFACT_IDENTITY_INVALID'
+  | 'REVIEW_ARTIFACT_NOT_REGULAR'
+  | 'REVIEW_LEDGER_INVALID'
+  | 'REVIEW_SUMMARY_NOT_FOUND'
+  | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
+  | 'REVIEW_SUMMARY_COUNT_MISMATCH'
+  | 'REVIEW_ARTIFACT_CONFLICT'
+  | 'REVIEW_PROVENANCE_INVALID'
+  | 'REVIEW_TEMP_WRITE_FAILED'
+  | 'REVIEW_RENAME_FAILED';
+type ReviewFinalizationError = { code: ReviewFinalizationErrorCode; message: string };
+type ReviewFinalizationRequest = {
+  taskRef: string;
+  stage: string;
+  artifact: string;
+  orchestrated?: boolean;
+  dryRun?: boolean;
+};
+type ReviewFinalizationResult = {
+  status: 'planned' | 'applied' | 'no-op' | 'failed';
+  changed: boolean;
+  intent: 'finalize-summary';
+  requestRef: string;
+  taskId: string | null;
+  stage: string;
+  artifact: string;
+  stageStatus: LedgerStageStatus | null;
+  operations: readonly {
+    kind: 'artifact';
+    artifact: string;
+    operation: 'update';
+  }[];
+  error: ReviewFinalizationError | null;
+};
+type ReviewFileSystem = {
+  readFileSync: (file: string) => string;
+  statModeSync: (file: string) => number;
+  writeFileSync: (file: string, content: string, mode: number) => void;
+  renameSync: (from: string, to: string) => void;
+  unlinkSync: (file: string) => void;
+};
+type ReviewFinalizationOptions = {
+  repoRoot?: string;
+  randomSuffix?: () => string;
+  fileSystem?: Partial<ReviewFileSystem>;
+};
+
+const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code'; action: string }> = {
+  analysis: { family: 'review-analysis', action: 'Review Analysis' },
+  plan: { family: 'review-plan', action: 'Review Plan' },
+  code: { family: 'review-code', action: 'Review Code' }
+};
+const DEFAULT_FILE_SYSTEM: ReviewFileSystem = {
+  readFileSync: (file) => fs.readFileSync(file, 'utf8'),
+  statModeSync: (file) => fs.statSync(file).mode,
+  writeFileSync: (file, content, mode) => fs.writeFileSync(file, content, { encoding: 'utf8', flag: 'wx', mode }),
+  renameSync: (from, to) => fs.renameSync(from, to),
+  unlinkSync: (file) => fs.unlinkSync(file)
+};
+
+function failed(
+  request: ReviewFinalizationRequest,
+  code: ReviewFinalizationErrorCode,
+  message: string,
+  taskId: string | null = null,
+  stageStatus: LedgerStageStatus | null = null
+): ReviewFinalizationResult {
+  return {
+    status: 'failed',
+    changed: false,
+    intent: 'finalize-summary',
+    requestRef: request.taskRef,
+    taskId,
+    stage: request.stage,
+    artifact: request.artifact,
+    stageStatus,
+    operations: [],
+    error: { code, message }
+  };
+}
+
+function openReviewRound(content: string, action: string, round: number): boolean {
+  const section = locateActivityLog(content);
+  if (!section) return false;
+  const expected = `${action} (Round ${round})`;
+  return pairEntries(section.entries).filter((row) => (
+    row.step === expected && Boolean(row.started) && !row.done
+  )).length === 1;
+}
+
+function cleanupTemp(fileSystem: ReviewFileSystem, tempPath: string): void {
+  try {
+    fileSystem.unlinkSync(tempPath);
+  } catch {
+    // Best-effort cleanup preserves the primary failure.
+  }
+}
+
+function finalizeReviewSummaryUnlocked(
+  request: ReviewFinalizationRequest,
+  options: ReviewFinalizationOptions = {}
+): ReviewFinalizationResult {
+  const stage = request.stage as ReviewStage;
+  const spec = STAGES[stage];
+  if (!spec) return failed(request, 'REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
+  if (!request.taskRef || !request.artifact) {
+    return failed(request, 'REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
+  }
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(request, resolved.code, resolved.message, resolved.taskId);
+  if (resolved.state !== 'active') {
+    return failed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  }
+  const parsedArtifact = parseArtifactName(request.artifact);
+  if (!parsedArtifact || parsedArtifact.family !== spec.family) {
+    return failed(
+      request,
+      'REVIEW_ARTIFACT_IDENTITY_INVALID',
+      `artifact '${request.artifact}' does not match ${spec.family}`,
+      resolved.taskId
+    );
+  }
+  const validated = validateCompletedArtifact(
+    resolved.taskDir,
+    spec.family,
+    request.artifact,
+    parsedArtifact.round
+  );
+  if (!validated.ok) {
+    const code = validated.error.code === 'ARTIFACT_NOT_REGULAR'
+      ? 'REVIEW_ARTIFACT_NOT_REGULAR'
+      : 'REVIEW_ARTIFACT_IDENTITY_INVALID';
+    return failed(request, code, validated.error.message, resolved.taskId);
+  }
+
+  const fileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
+  let taskContent: string;
+  let artifactContent: string;
+  try {
+    taskContent = fileSystem.readFileSync(resolved.taskMdPath);
+    artifactContent = fileSystem.readFileSync(validated.artifact.path);
+  } catch (error) {
+    return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
+  }
+  if (!openReviewRound(taskContent, spec.action, parsedArtifact.round)) {
+    return failed(
+      request,
+      'REVIEW_ARTIFACT_IDENTITY_INVALID',
+      `${request.artifact} does not have one matching open started review event`,
+      resolved.taskId
+    );
+  }
+  const execution = validateLifecycleExecution(request.taskRef, {
+    mode: request.orchestrated ? 'orchestrated' : 'standalone',
+    identity: {
+      stage: spec.family,
+      round: parsedArtifact.round,
+      artifact: request.artifact,
+      role: 'reviewer'
+    },
+    dryRun: request.dryRun
+  }, { repoRoot: options.repoRoot });
+  if (!execution.ok) {
+    return failed(
+      request,
+      'REVIEW_PROVENANCE_INVALID',
+      `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`,
+      resolved.taskId
+    );
+  }
+
+  let rows;
+  try {
+    rows = parseLedger(taskContent);
+  } catch (error) {
+    return failed(request, 'REVIEW_LEDGER_INVALID', String(error), resolved.taskId);
+  }
+  const ledgerError = validateLedgerRows(rows);
+  if (ledgerError) {
+    return failed(
+      request,
+      'REVIEW_LEDGER_INVALID',
+      `${ledgerError.code}: ${ledgerError.message}`,
+      resolved.taskId
+    );
+  }
+  const stageStatus = summarizeLedgerStage(rows, stage);
+  const transformed = finalizeReviewSummaryContent(
+    artifactContent,
+    stageStatus.unresolvedFindingCounts
+  );
+  if (!transformed.ok) {
+    return failed(request, transformed.code, transformed.message, resolved.taskId, stageStatus);
+  }
+  if (!transformed.changed) {
+    return {
+      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
+      status: 'no-op',
+      error: null
+    };
+  }
+  const operations = [{ kind: 'artifact' as const, artifact: request.artifact, operation: 'update' as const }];
+  if (request.dryRun) {
+    return {
+      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
+      status: 'planned',
+      changed: true,
+      operations,
+      error: null
+    };
+  }
+
+  const tempPath = path.join(
+    resolved.taskDir,
+    `.${request.artifact}.tmp-${process.pid}-${(options.randomSuffix ?? randomUUID)()}`
+  );
+  let mode: number;
+  try {
+    mode = fileSystem.statModeSync(validated.artifact.path);
+    fileSystem.writeFileSync(tempPath, transformed.content, mode);
+  } catch (error) {
+    cleanupTemp(fileSystem, tempPath);
+    return failed(request, 'REVIEW_TEMP_WRITE_FAILED', String(error), resolved.taskId, stageStatus);
+  }
+  try {
+    if (fileSystem.readFileSync(validated.artifact.path) !== artifactContent) {
+      cleanupTemp(fileSystem, tempPath);
+      return failed(
+        request,
+        'REVIEW_ARTIFACT_CONFLICT',
+        `${request.artifact} changed during finalization`,
+        resolved.taskId,
+        stageStatus
+      );
+    }
+    fileSystem.renameSync(tempPath, validated.artifact.path);
+  } catch (error) {
+    cleanupTemp(fileSystem, tempPath);
+    return failed(request, 'REVIEW_RENAME_FAILED', String(error), resolved.taskId, stageStatus);
+  }
+  return {
+    status: 'applied',
+    changed: true,
+    intent: 'finalize-summary',
+    requestRef: request.taskRef,
+    taskId: resolved.taskId,
+    stage,
+    artifact: request.artifact,
+    stageStatus,
+    operations,
+    error: null
+  };
+}
+
+function finalizeReviewSummary(
+  request: ReviewFinalizationRequest,
+  options: ReviewFinalizationOptions = {}
+): ReviewFinalizationResult {
+  if (request.dryRun) return finalizeReviewSummaryUnlocked(request, options);
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, options);
+  try {
+    return withTaskExecutionLock(
+      resolved.repoRoot,
+      resolved.taskId,
+      'task-review.finalize-summary',
+      () => finalizeReviewSummaryUnlocked(request, options)
+    );
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    return failed(
+      request,
+      'REVIEW_PROVENANCE_INVALID',
+      `${error.code}: ${error.message}`,
+      resolved.taskId
+    );
+  }
+}
+
+export { finalizeReviewSummary };
+export type {
+  ReviewFinalizationError,
+  ReviewFinalizationErrorCode,
+  ReviewFinalizationOptions,
+  ReviewFinalizationRequest,
+  ReviewFinalizationResult
+};

package/lib/task/review-fingerprint.ts

@@ -56,6 +56,11 @@ export function extractReviewBaseline(content: string): string {
   return match ? match[1]!.trim().replace(/`/g, "") : "";
 }
 
+export function extractReviewDiffBase(content: string): string {
+  const match = String(content).match(/^[-*]?\s*\*\*(?:审查差异基线|Reviewed Diff Base)\*\*[:：]\s*(.*?)\s*$/m);
+  return match ? match[1]!.trim().replace(/`/g, "") : "";
+}
+
 export function extractReviewDiffFingerprint(content: string): string {
   const match = String(content).match(/^[-*]?\s*\*\*(?:审查差异指纹|Reviewed Diff Fingerprint)\*\*[:：]\s*(.*?)\s*$/m);
   return match ? match[1]!.trim().replace(/`/g, "") : "";