@fitlab-ai/agent-infra 0.9.12 → 0.9.14

package/lib/task/qualification-confirmation.ts

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+
+import { appendActivityEntry, locateActivityLog } from './activity-log.ts';
+import { CONFIRMATION_COLUMNS, CONFIRMATION_HEADINGS, constraintDigest, parseQualificationConfirmations, parseTaskQualification } from './qualification-audit.ts';
+import type { QualificationConfirmation } from './qualification-audit.ts';
+import { findSectionHeading } from './sections.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import type { TaskOperationSummary, TaskWriteOptions } from './write.ts';
+
+type QualificationConfirmationRequest = {
+  taskRef: string;
+  constraintId: string;
+  expectedDigest: string;
+  rationale: string;
+  operation?: 'confirm' | 'supersede' | 'revoke';
+  dryRun?: boolean;
+};
+type QualificationConfirmationResult = {
+  status: 'planned' | 'applied' | 'no-op' | 'failed';
+  changed: boolean;
+  taskId: string | null;
+  qcrId: string | null;
+  requestId: string | null;
+  operations: readonly TaskOperationSummary[];
+  error: { code: string; message: string } | null;
+};
+
+function failed(code: string, message: string, taskId: string | null = null): QualificationConfirmationResult {
+  return { status: 'failed', changed: false, taskId, qcrId: null, requestId: null, operations: [], error: { code, message } };
+}
+
+function nextQcrId(content: string): string {
+  let max = 0;
+  for (const match of content.matchAll(/^\|\s*(QCR-(\d+))\s*\|/gm)) max = Math.max(max, Number(match[2]));
+  return `QCR-${max + 1}`;
+}
+
+function requestIdFor(taskId: string, constraintId: string, expectedDigest: string, rationale: string, timestamp: string): string {
+  const hash = createHash('sha256').update(JSON.stringify([taskId, constraintId, expectedDigest, rationale, timestamp])).digest('hex');
+  return `QCR-REQUEST-${hash.slice(0, 20)}`;
+}
+
+function renderConfirmations(rows: readonly QualificationConfirmation[]): string {
+  return [
+    `| ${CONFIRMATION_COLUMNS.join(' | ')} |`,
+    `| ${CONFIRMATION_COLUMNS.map(() => '---').join(' | ')} |`,
+    ...rows.map((row) => [row.qcrId, row.constraintId, row.actor, row.entrypoint, row.requestId, row.approvedDigest, row.confirmedAt, row.rationale]
+      .map((value) => value.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/[\r\n]/g, ' '))
+      .join(' | ')).map((line) => `| ${line} |`)
+  ].join('\n');
+}
+
+function applyQualificationConfirmation(request: QualificationConfirmationRequest, options: TaskWriteOptions = {}): QualificationConfirmationResult {
+  if (!request || typeof request !== 'object' || !request.taskRef || !/^C-[1-9]\d*$/.test(request.constraintId) || !/^[a-f0-9]{64}$/i.test(request.expectedDigest) || !request.rationale?.trim() || /[\r\n]/.test(request.rationale)) {
+    return failed('QUALIFICATION_CONFIRMATION_INVALID', 'taskRef, constraintId, expectedDigest, and a single-line rationale are required');
+  }
+  const resolved = resolveTaskRef(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;
+  try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
+  catch (error) { return failed('TASK_READ_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId); }
+  const parsed = parseTaskQualification(content);
+  if (!parsed.ok) return failed(parsed.code, parsed.message, resolved.taskId);
+  if (!parsed.qualification.present) return failed('QUALIFICATION_TASK_CONTRACT_MISSING', 'task qualification contract is missing', resolved.taskId);
+  const constraint = parsed.qualification.constraints.find((row) => row.constraintId === request.constraintId);
+  if (!constraint) return failed('QUALIFICATION_CONSTRAINT_UNKNOWN', `unknown constraint '${request.constraintId}'`, resolved.taskId);
+  const operation = request.operation ?? 'confirm';
+  const existing = parseQualificationConfirmations(content);
+  if (!existing.ok) return failed(existing.code, existing.message, resolved.taskId);
+  const previous = existing.confirmations.find((row) => row.qcrId === constraint.approvalEvidence);
+  if (operation === 'confirm' && constraint.status === 'confirmed') {
+    if (previous?.constraintId === constraint.constraintId && previous.approvedDigest === constraint.digest && previous.rationale === request.rationale.trim()) {
+      return { status: 'no-op', changed: false, taskId: resolved.taskId, qcrId: previous.qcrId, requestId: previous.requestId, operations: [], error: null };
+    }
+    return failed('QUALIFICATION_CONFIRMATION_CONFLICT', `constraint '${request.constraintId}' is already confirmed with different evidence`, resolved.taskId);
+  }
+  const transitionStatus = operation === 'supersede' ? 'superseded' : 'open';
+  if (operation !== 'confirm' && constraint.status === transitionStatus && !constraint.approvalEvidence) {
+    return { status: 'no-op', changed: false, taskId: resolved.taskId, qcrId: null, requestId: null, operations: [], error: null };
+  }
+  if (operation !== 'confirm' && constraint.status !== 'confirmed') return failed('QUALIFICATION_CONFIRMATION_REQUIRED', `constraint '${request.constraintId}' is not confirmed`, resolved.taskId);
+  if (parsed.qualification.constraintDigest !== request.expectedDigest) return failed('QUALIFICATION_DIGEST_CONFLICT', 'constraint digest changed before human confirmation', resolved.taskId);
+  let metadata;
+  try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
+  catch (error) { return failed('METADATA_CAPTURE_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId); }
+  const qcrId = operation === 'confirm' ? nextQcrId(content) : null;
+  const requestId = operation === 'confirm' ? requestIdFor(resolved.taskId, request.constraintId, request.expectedDigest, request.rationale.trim(), metadata.timestamp) : null;
+  const confirmedConstraint = qcrId ? {
+    constraintId: constraint.constraintId, statement: constraint.statement, status: 'confirmed' as const,
+    authority: 'human-declared', source: constraint.source, evidence: constraint.evidence,
+    derivedFrom: constraint.derivedFrom, approvalEvidence: qcrId
+  } : null;
+  const confirmation = confirmedConstraint && qcrId && requestId ? {
+    qcrId, constraintId: request.constraintId, actor: 'human-declared' as const, entrypoint: 'task-qualification' as const,
+    requestId, approvedDigest: constraintDigest(confirmedConstraint), confirmedAt: metadata.timestamp, rationale: request.rationale.trim()
+  } : null;
+  const confirmations = confirmation ? [...existing.confirmations, confirmation] : existing.confirmations;
+  const activity = locateActivityLog(content);
+  if (!activity) return failed('QUALIFICATION_ACTIVITY_MISSING', 'task has no unique Activity Log section', resolved.taskId);
+  const mutations: Parameters<typeof writeTask>[0]['mutations'][number][] = [
+    {
+      kind: 'table-row', action: 'upsert', sectionAliases: ['约束', 'Constraints'], columns: ['constraint_id', 'statement', 'status', 'authority', 'source', 'evidence', 'derived_from', 'approval_evidence'], keyColumn: 'constraint_id', key: constraint.constraintId,
+      values: { statement: constraint.statement, status: operation === 'confirm' ? 'confirmed' : transitionStatus, authority: operation === 'confirm' ? 'human-declared' : constraint.authority, source: constraint.source, evidence: constraint.evidence, derived_from: constraint.derivedFrom.join(','), approval_evidence: qcrId ?? '' }
+    },
+    ...(operation === 'confirm' ? [{ kind: 'section' as const, aliases: CONFIRMATION_HEADINGS, heading: findSectionHeading(content, [...CONFIRMATION_HEADINGS]), body: renderConfirmations(confirmations) }] : []),
+    { kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: activity.heading, body: appendActivityEntry(activity, { time: metadata.timestamp, step: 'Qualification Confirmation', agent: 'human', note: operation === 'confirm' ? `${request.constraintId} confirmed → ${qcrId}` : `${request.constraintId} ${operation}d` }) }
+  ];
+  const result = 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 (result.status === 'failed') return failed(result.error.code, result.error.message, result.taskId);
+  return { status: result.status, changed: result.changed, taskId: result.taskId, qcrId, requestId, operations: result.operations, error: null };
+}
+
+export { applyQualificationConfirmation };
+export type { QualificationConfirmationRequest, QualificationConfirmationResult };

package/lib/task/qualification-intents.ts

@@ -0,0 +1,150 @@
+import fs from 'node:fs';
+
+import { CONSTRAINT_COLUMNS, CANDIDATE_COLUMNS, parseTaskQualification } from './qualification-audit.ts';
+import type { CandidateStatus, ConstraintStatus } from './qualification-audit.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import type { TaskOperationSummary, TaskWriteOptions } from './write.ts';
+
+type QualificationConstraintProposal = {
+  constraintId: string;
+  statement: string;
+  status: Exclude<ConstraintStatus, 'confirmed'>;
+  authority: string;
+  source: string;
+  evidence: string;
+  derivedFrom: readonly string[];
+  approvalEvidence: string;
+};
+type QualificationCandidateProposal = {
+  candidateId: string;
+  statement: string;
+  status: Extract<CandidateStatus, 'pending'>;
+  constraintIds: readonly string[];
+  impact: string;
+  evidence: string;
+};
+type QualificationProposalRequest = {
+  taskRef: string;
+  expectedTaskInputDigest: string;
+  constraints?: readonly QualificationConstraintProposal[];
+  candidates?: readonly QualificationCandidateProposal[];
+  dryRun?: boolean;
+};
+type QualificationProposalResult = {
+  status: 'planned' | 'applied' | 'no-op' | 'failed';
+  changed: boolean;
+  taskId: string | null;
+  operations: readonly TaskOperationSummary[];
+  error: { code: string; message: string } | null;
+};
+
+function failed(code: string, message: string, taskId: string | null = null): QualificationProposalResult {
+  return { status: 'failed', changed: false, taskId, operations: [], error: { code, message } };
+}
+
+function validSingleLine(value: unknown): value is string {
+  return typeof value === 'string' && Boolean(value.trim()) && !/[\r\n]/.test(value);
+}
+
+function assertProposalKeys(value: unknown, keys: readonly string[], label: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  const record = value as Record<string, unknown>;
+  const unexpected = Object.keys(record).find((key) => !keys.includes(key));
+  if (unexpected) throw new Error(`${label} does not accept '${unexpected}'`);
+  return record;
+}
+
+function parseConstraintProposal(value: unknown): QualificationConstraintProposal {
+  const row = assertProposalKeys(value, ['constraintId', 'statement', 'status', 'authority', 'source', 'evidence', 'derivedFrom', 'approvalEvidence'], 'constraint proposal');
+  for (const key of ['constraintId', 'statement', 'status', 'authority', 'source', 'evidence', 'approvalEvidence']) {
+    if (typeof row[key] !== 'string' || /[\r\n]/.test(row[key] as string)) throw new Error(`constraint proposal '${key}' must be a single-line string`);
+  }
+  if (!/^C-[1-9]\d*$/.test(row.constraintId as string)) throw new Error(`constraint proposal id '${row.constraintId as string}' is invalid`);
+  if (row.status === 'confirmed' || !['derived', 'assumption', 'open', 'conflicted', 'superseded'].includes(row.status as string)) throw new Error('proposal cannot write confirmed constraint status');
+  if ((row.approvalEvidence as string) !== '') throw new Error('proposal cannot write approval_evidence');
+  if (!Array.isArray(row.derivedFrom) || row.derivedFrom.some((item) => typeof item !== 'string' || !/^C-[1-9]\d*$/.test(item))) throw new Error('constraint proposal derivedFrom is invalid');
+  return {
+    constraintId: row.constraintId as string, statement: row.statement as string, status: row.status as Exclude<ConstraintStatus, 'confirmed'>,
+    authority: row.authority as string, source: row.source as string, evidence: row.evidence as string,
+    derivedFrom: [...row.derivedFrom as string[]], approvalEvidence: ''
+  };
+}
+
+function parseCandidateProposal(value: unknown): QualificationCandidateProposal {
+  const row = assertProposalKeys(value, ['candidateId', 'statement', 'status', 'constraintIds', 'impact', 'evidence'], 'candidate proposal');
+  for (const key of ['candidateId', 'statement', 'status', 'impact', 'evidence']) if (!validSingleLine(row[key])) throw new Error(`candidate proposal '${key}' must be a non-empty single-line string`);
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(row.candidateId as string)) throw new Error(`candidate proposal id '${row.candidateId as string}' is invalid`);
+  if (row.status !== 'pending') throw new Error('proposal can only write pending candidate status');
+  if (!Array.isArray(row.constraintIds) || row.constraintIds.some((item) => typeof item !== 'string' || !/^C-[1-9]\d*$/.test(item))) throw new Error('candidate proposal constraintIds is invalid');
+  return row as unknown as QualificationCandidateProposal;
+}
+
+function proposalValues(request: QualificationProposalRequest): { constraints: QualificationConstraintProposal[]; candidates: QualificationCandidateProposal[] } {
+  if (!/^[a-f0-9]{64}$/i.test(request.expectedTaskInputDigest)) throw new Error('expectedTaskInputDigest must be a sha256 digest');
+  if (Object.keys(request).some((key) => !['taskRef', 'expectedTaskInputDigest', 'constraints', 'candidates', 'dryRun'].includes(key))) throw new Error('proposal contains an unsupported field');
+  if (!Array.isArray(request.constraints) && request.constraints !== undefined) throw new Error('constraints must be an array');
+  if (!Array.isArray(request.candidates) && request.candidates !== undefined) throw new Error('candidates must be an array');
+  return {
+    constraints: (request.constraints ?? []).map(parseConstraintProposal),
+    candidates: (request.candidates ?? []).map(parseCandidateProposal)
+  };
+}
+
+function applyQualificationProposal(request: QualificationProposalRequest, options: TaskWriteOptions = {}): QualificationProposalResult {
+  if (!request || typeof request !== 'object' || !validSingleLine(request.taskRef)) return failed('QUALIFICATION_PROPOSAL_INVALID', 'taskRef is required');
+  let values: ReturnType<typeof proposalValues>;
+  try { values = proposalValues(request); }
+  catch (error) { return failed('QUALIFICATION_PROPOSAL_INVALID', error instanceof Error ? error.message : String(error)); }
+  if (values.constraints.length === 0 && values.candidates.length === 0) return failed('QUALIFICATION_PROPOSAL_INVALID', 'proposal must contain a constraint or candidate');
+  const resolved = resolveTaskRef(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;
+  try { content = fs.readFileSync(resolved.taskMdPath, 'utf8'); }
+  catch (error) { return failed('TASK_READ_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId); }
+  const parsed = parseTaskQualification(content);
+  if (!parsed.ok) return failed(parsed.code, parsed.message, resolved.taskId);
+  if (!parsed.qualification.present) return failed('QUALIFICATION_TASK_CONTRACT_MISSING', 'task qualification contract is missing', resolved.taskId);
+  const currentConstraintMap = new Map(parsed.qualification.constraints.map((row) => [row.constraintId, row]));
+  const currentCandidateMap = new Map(parsed.qualification.candidates.map((row) => [row.candidateId, row]));
+  const proposalAlreadyApplied = values.constraints.every((row) => {
+    const current = currentConstraintMap.get(row.constraintId);
+    return current && current.statement === row.statement && current.status === row.status && current.authority === row.authority
+      && current.source === row.source && current.evidence === row.evidence && current.derivedFrom.join(',') === row.derivedFrom.join(',') && current.approvalEvidence === '';
+  }) && values.candidates.every((row) => {
+    const current = currentCandidateMap.get(row.candidateId);
+    return current && current.statement === row.statement && current.status === row.status && current.constraintIds.join(',') === row.constraintIds.join(',')
+      && current.impact === row.impact && current.evidence === row.evidence;
+  });
+  if (parsed.qualification.taskInputDigest !== request.expectedTaskInputDigest) {
+    return proposalAlreadyApplied
+      ? { status: 'no-op', changed: false, taskId: resolved.taskId, operations: [], error: null }
+      : failed('QUALIFICATION_DIGEST_CONFLICT', 'task qualification input changed before proposal was applied', resolved.taskId);
+  }
+  for (const row of values.constraints) {
+    const current = currentConstraintMap.get(row.constraintId);
+    if (current?.status === 'confirmed') return failed('QUALIFICATION_CONFIRMATION_REQUIRED', `confirmed constraint '${row.constraintId}' must be superseded or revoked through task-qualification`, resolved.taskId);
+  }
+  const knownConstraintIds = new Set([...parsed.qualification.constraints.map((row) => row.constraintId), ...values.constraints.map((row) => row.constraintId)]);
+  for (const row of values.constraints) for (const parent of row.derivedFrom) if (!knownConstraintIds.has(parent)) return failed('QUALIFICATION_CONSTRAINT_UNKNOWN', `constraint proposal '${row.constraintId}' references unknown '${parent}'`, resolved.taskId);
+  for (const row of values.candidates) for (const id of row.constraintIds) if (!knownConstraintIds.has(id)) return failed('QUALIFICATION_CONSTRAINT_UNKNOWN', `candidate proposal '${row.candidateId}' references unknown '${id}'`, resolved.taskId);
+  const mutations: Parameters<typeof writeTask>[0]['mutations'][number][] = [];
+  for (const row of values.constraints) {
+    mutations.push({ kind: 'table-row', action: 'upsert', sectionAliases: ['约束', 'Constraints'], columns: CONSTRAINT_COLUMNS, keyColumn: 'constraint_id', key: row.constraintId, values: { statement: row.statement, status: row.status, authority: row.authority, source: row.source, evidence: row.evidence, derived_from: row.derivedFrom.join(','), approval_evidence: '' } });
+  }
+  for (const row of values.candidates) {
+    mutations.push({ kind: 'table-row', action: 'upsert', sectionAliases: ['候选与否决方案', 'Candidate and Rejected Options', 'Candidates and Rejected Options', 'Candidates and Rejected Alternatives'], columns: CANDIDATE_COLUMNS, keyColumn: 'candidate_id', key: row.candidateId, values: { statement: row.statement, status: row.status, constraint_ids: row.constraintIds.join(','), impact: row.impact, evidence: row.evidence } });
+  }
+  // Only the submitted rows are mutated; no actor, confirmation, or QCR fields
+  // can be smuggled into this internal proposal operation.
+  let metadata;
+  try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
+  catch (error) { return failed('METADATA_CAPTURE_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId); }
+  const result = 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 (result.status === 'failed') return failed(result.error.code, result.error.message, result.taskId);
+  return { status: result.status, changed: result.changed, taskId: result.taskId, operations: result.operations, error: null };
+}
+
+export { applyQualificationProposal };
+export type { QualificationCandidateProposal, QualificationConstraintProposal, QualificationProposalRequest, QualificationProposalResult };

package/lib/task/review-artifacts.ts

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { scanVisibleMarkdown } from './decision-details.ts';
+
 type ReviewFindingCounts = {
   blocker: number;
   major: number;
@@ -77,29 +79,21 @@ function normalizeVerdict(raw: unknown): ReviewVerdict | '' {
 }
 
 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 '';
-  const sectionLines = [];
-  for (let index = start + 1; index < lines.length; index += 1) {
-    if (/^##\s+/.test(lines[index]!)) break;
-    sectionLines.push(lines[index]);
-  }
-  return sectionLines.join('\n');
+  const scanned = scanVisibleMarkdown(content);
+  const heading = scanned.headings.find((item) => item.level === 2 && nameSet.has(item.text));
+  if (!heading) return '';
+  const next = scanned.headings.find((item) => item.start > heading.start && item.level <= 2);
+  return content.slice(heading.end, next?.start ?? content.length);
 }
 
 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));
+  const scanned = scanVisibleMarkdown(content);
+  const summaries = scanned.headings.filter((heading) => heading.level === 2 && SUMMARY_HEADINGS.has(heading.text));
   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 next = scanned.headings.find((heading) => heading.start > summary.start && heading.level <= 2);
+  return { start: summary.end, end: next?.start ?? content.length };
 }
 
 function uniqueLine(
@@ -107,14 +101,19 @@ function uniqueLine(
   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)];
+  const matches: Array<{ value: string; index: number; length: number }> = [];
+  for (const line of scanVisibleMarkdown(content).lines) {
+    if (line.start < bounds.start || line.start >= bounds.end) continue;
+    pattern.lastIndex = 0;
+    const match = pattern.exec(line.text);
+    if (match) matches.push({ value: match[1]!, index: line.start + match.index, length: match[0].length });
+  }
   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
+    value: match.value,
+    start: match.index,
+    end: match.index + match.length
   };
 }
 

package/lib/task/review-finalization.ts

@@ -14,6 +14,10 @@ import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-
 import type { ResolveTaskRefErrorCode } from './resolve-ref.ts';
 import { allowsManualOverride } from './guard-override.ts';
 import type { ManualOverrideCapability } from './guard-override.ts';
+import { getArtifactSchema } from './artifact-schema.ts';
+import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.ts';
+import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.ts';
+import type { ArtifactRepairOperation } from './artifact-operations.ts';
 
 type ReviewFinalizationErrorCode =
   | ResolveTaskRefErrorCode
@@ -26,6 +30,7 @@ type ReviewFinalizationErrorCode =
   | 'REVIEW_SUMMARY_NOT_FOUND'
   | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
   | 'REVIEW_SUMMARY_COUNT_MISMATCH'
+  | 'REVIEW_ARTIFACT_STRUCTURE_INVALID'
   | 'REVIEW_DECISION_DETAIL_INVALID'
   | 'REVIEW_ARTIFACT_CONFLICT'
   | 'REVIEW_PROVENANCE_INVALID'
@@ -48,6 +53,10 @@ type ReviewFinalizationResult = {
   stage: string;
   artifact: string;
   stageStatus: LedgerStageStatus | null;
+  artifactSha256: string | null;
+  semanticDigest: string | null;
+  repairable: boolean;
+  operation: ArtifactRepairOperation | null;
   operations: readonly {
     kind: 'artifact';
     artifact: string;
@@ -88,7 +97,8 @@ function failed(
   code: ReviewFinalizationErrorCode,
   message: string,
   taskId: string | null = null,
-  stageStatus: LedgerStageStatus | null = null
+  stageStatus: LedgerStageStatus | null = null,
+  extra: Partial<ReviewFinalizationResult> = {}
 ): ReviewFinalizationResult {
   return {
     status: 'failed',
@@ -99,8 +109,13 @@ function failed(
     stage: request.stage,
     artifact: request.artifact,
     stageStatus,
+    artifactSha256: null,
+    semanticDigest: null,
+    repairable: false,
+    operation: null,
     operations: [],
-    error: { code, message }
+    error: { code, message },
+    ...extra
   };
 }
 
@@ -167,6 +182,80 @@ function finalizeReviewSummaryUnlocked(
   } catch (error) {
     return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
   }
+  const schema = getArtifactSchema(spec.family);
+  const structure = schema ? inspectArtifactContract(artifactContent, schema) : null;
+  const artifactSha256 = sha256Content(artifactContent);
+  const artifactSemanticDigest = canonicalSemanticDigest(artifactContent);
+  let repairIntent;
+  try {
+    repairIntent = readArtifactRepairIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
+  } catch (error) {
+    return failed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId, null, {
+      artifactSha256,
+      semanticDigest: artifactSemanticDigest
+    });
+  }
+  if (structure && !structure.ok) {
+    const repairable = structure.repair !== null && structure.diagnostics.length === 1 && structure.diagnostics[0]?.repairable === true;
+    if (repairable) {
+      if (repairIntent && (
+        repairIntent.state !== 'awaiting-repair' ||
+        repairIntent.artifactSha256 !== artifactSha256 ||
+        repairIntent.semanticDigest !== structure.semanticDigest
+      )) {
+        return failed(request, 'REVIEW_PROVENANCE_INVALID', 'a different review repair baseline is already recorded for this artifact', resolved.taskId, null, {
+          artifactSha256,
+          semanticDigest: structure.semanticDigest
+        });
+      }
+      try {
+        if (!repairIntent) {
+          writeArtifactRepairIntent(resolved.repoRoot, {
+            version: 1,
+            taskId: resolved.taskId,
+            family: spec.family,
+            artifact: request.artifact,
+            state: 'awaiting-repair',
+            baselineSemanticDigest: structure.semanticDigest,
+            artifactSha256,
+            semanticDigest: structure.semanticDigest
+          });
+        }
+      } catch (error) {
+        return failed(request, 'REVIEW_PROVENANCE_INVALID', `cannot record repair provenance: ${String(error)}`, resolved.taskId, null, {
+          artifactSha256,
+          semanticDigest: structure.semanticDigest,
+          operation: structure.repair
+        });
+      }
+    }
+    return failed(
+      request,
+      'REVIEW_ARTIFACT_STRUCTURE_INVALID',
+      structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '),
+      resolved.taskId,
+      null,
+      {
+        artifactSha256,
+        semanticDigest: structure.semanticDigest,
+        repairable,
+        operation: structure.repair
+      }
+    );
+  }
+  if (repairIntent?.state === 'awaiting-repair' && repairIntent.baselineSemanticDigest !== artifactSemanticDigest) {
+    return failed(request, 'REVIEW_PROVENANCE_INVALID', 'the repaired review artifact semantic digest does not match the recorded repair baseline', resolved.taskId, null, {
+      artifactSha256,
+      semanticDigest: artifactSemanticDigest
+    });
+  }
+  if ((repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')
+    && (repairIntent.artifactSha256 !== artifactSha256 || repairIntent.semanticDigest !== artifactSemanticDigest)) {
+    return failed(request, 'REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', resolved.taskId, null, {
+      artifactSha256,
+      semanticDigest: artifactSemanticDigest
+    });
+  }
   if (!openReviewRound(taskContent, spec.action, parsedArtifact.round)) {
     return failed(
       request,
@@ -232,8 +321,26 @@ function finalizeReviewSummaryUnlocked(
     return failed(request, transformed.code, transformed.message, resolved.taskId, stageStatus);
   }
   if (!transformed.changed) {
+    if (repairIntent?.state === 'awaiting-repair') {
+      try {
+        writeArtifactRepairIntent(resolved.repoRoot, {
+          ...repairIntent,
+          state: 'passed',
+          artifactSha256,
+          semanticDigest: artifactSemanticDigest
+        });
+      } catch (error) {
+        return failed(request, 'REVIEW_PROVENANCE_INVALID', `cannot record repaired review provenance: ${String(error)}`, resolved.taskId, stageStatus, {
+          artifactSha256,
+          semanticDigest: artifactSemanticDigest
+        });
+      }
+    }
     return {
-      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
+      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus, {
+        artifactSha256,
+        semanticDigest: artifactSemanticDigest
+      }),
       status: 'no-op',
       error: null
     };
@@ -241,7 +348,10 @@ function finalizeReviewSummaryUnlocked(
   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),
+      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus, {
+        artifactSha256: sha256Content(transformed.content),
+        semanticDigest: canonicalSemanticDigest(transformed.content)
+      }),
       status: 'planned',
       changed: true,
       operations,
@@ -277,6 +387,21 @@ function finalizeReviewSummaryUnlocked(
     cleanupTemp(fileSystem, tempPath);
     return failed(request, 'REVIEW_RENAME_FAILED', String(error), resolved.taskId, stageStatus);
   }
+  if (repairIntent?.state === 'awaiting-repair') {
+    try {
+      writeArtifactRepairIntent(resolved.repoRoot, {
+        ...repairIntent,
+        state: 'passed',
+        artifactSha256: sha256Content(transformed.content),
+        semanticDigest: canonicalSemanticDigest(transformed.content)
+      });
+    } catch (error) {
+      return failed(request, 'REVIEW_PROVENANCE_INVALID', `cannot record repaired review provenance: ${String(error)}`, resolved.taskId, stageStatus, {
+        artifactSha256: sha256Content(transformed.content),
+        semanticDigest: canonicalSemanticDigest(transformed.content)
+      });
+    }
+  }
   return {
     status: 'applied',
     changed: true,
@@ -286,6 +411,10 @@ function finalizeReviewSummaryUnlocked(
     stage,
     artifact: request.artifact,
     stageStatus,
+    artifactSha256: sha256Content(transformed.content),
+    semanticDigest: canonicalSemanticDigest(transformed.content),
+    repairable: false,
+    operation: null,
     operations,
     error: null
   };

package/lib/task/review-fingerprint.ts

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { artifactName, maxRound } from "./review-artifacts.ts";
+import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from "./invalidation.ts";
 
 type ReviewedGitTree = string & { readonly __reviewedGitTree: unique symbol };
 const REVIEWED_TREE_RE = /^[a-f0-9]{40,64}$/;
@@ -46,15 +47,35 @@ export function findAuthoritativeReviewCodeArtifact(taskDir: string) {
   const entries = fs.existsSync(taskDir) ? fs.readdirSync(taskDir) : [];
   const round = maxRound(entries, "review-code");
   if (round === 0) {
-    return { ok: false, round: 0, fileName: null, path: null };
+    return { ok: false, round: 0, fileName: null, path: null, error: null };
   }
 
   const fileName = artifactName("review-code", round);
+  let taskContent: string;
+  try {
+    taskContent = fs.readFileSync(path.join(taskDir, "task.md"), "utf8");
+  } catch (error) {
+    return {
+      ok: false, round, fileName, path: null,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+  const invalidation = parseInvalidationDocument(taskContent);
+  if (!invalidation.ok) {
+    return { ok: false, round, fileName, path: null, error: invalidation.message };
+  }
+  if (invalidationBlocks(invalidation.document)) {
+    return { ok: false, round, fileName, path: null, error: "artifact invalidation is incomplete; reconcile task.md before using review-code" };
+  }
+  if (isArtifactInvalidated(invalidation.document, "review-code", fileName)) {
+    return { ok: false, round, fileName, path: null, error: `${fileName} is invalidated; re-run review-code` };
+  }
   return {
     ok: true,
     round,
     fileName,
-    path: path.join(taskDir, fileName)
+    path: path.join(taskDir, fileName),
+    error: null
   };
 }