@fitlab-ai/agent-infra 0.10.0 → 0.11.1

package/lib/task/orchestration.ts

@@ -57,8 +57,7 @@ import { extractReviewBaseline, extractReviewDiffBase, extractReviewTargetHead,
 import { resolveDeliveryTarget, resolveDiffBase, resolveTargetHead } from './delivery-target.ts';
 import { buildLifecycleFacts, canStart, recommendNext } from './capabilities.ts';
 import { hasOpenLifecycleExecution } from './activity-log.ts';
-import { invalidationBlocks } from './invalidation.ts';
-import type { InvalidationDocument } from './invalidation.ts';
+import { reconcileTaskInvalidation } from './invalidation-command.ts';
 import type { LifecycleAction, LifecycleFacts } from './capabilities.ts';
 import { normalizeAgentToken } from '../agent-clients/tokens.ts';
 
@@ -678,13 +677,11 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
   }
   let metadata: ReturnType<typeof parseTypedTaskFrontmatter>;
   let currentLedger: LedgerDocument | null = null;
-  let currentInvalidation: InvalidationDocument = { operations: [], targets: [] };
   if (resolved.state === 'active') {
     const contract = validateCurrentTaskContract(content);
     if (!contract.ok) return failed('ORCHESTRATION_CURRENT_CONTRACT_INVALID', contract.message, resolved.taskId);
     metadata = contract.metadata;
     currentLedger = contract.ledger;
-    currentInvalidation = contract.invalidation;
   } else {
     try {
       metadata = parseTypedTaskFrontmatter(content);
@@ -692,9 +689,6 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
       return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
   }
-  if (invalidationBlocks(currentInvalidation)) {
-    return failed('ORCHESTRATION_INVALIDATION_INCOMPLETE', 'artifact invalidation is incomplete; reconcile task.md before routing downstream work', resolved.taskId);
-  }
   let run: OrchestrationRun | null;
   try {
     run = readRun(resolved.taskDir, options);
@@ -711,6 +705,9 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
   const routed = routeFromFacts(facts.facts);
   if (!routed) return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
   if ('completion' in routed) {
+    if (facts.facts.executionBusy && !run?.pendingDelegation) {
+      return failed('ORCHESTRATION_EXECUTION_BUSY', 'clean completion requires no open lifecycle execution', resolved.taskId);
+    }
     const reviewRound = maxArtifactRound(fs.readdirSync(resolved.taskDir), 'review-code');
     const review = parseReviewSummary(fs.readFileSync(
       path.join(resolved.taskDir, artifactName('review-code', reviewRound)),
@@ -847,6 +844,14 @@ function prepareOrchestrationDelegationUnlocked(
     return failed('ORCHESTRATION_DELEGATION_BUSY', 'the repository already has a pending lifecycle delegation', resolved.taskId);
   }
   if (run.stepCount >= run.maxSteps) return pauseOrchestration(taskRef, 'ORCHESTRATION_MAX_STEPS', 'maximum orchestration steps reached', true, options);
+  const invalidation = reconcileTaskInvalidation(taskRef, { repoRoot: resolved.repoRoot });
+  if (invalidation.status === 'failed') {
+    return failed(
+      'ORCHESTRATION_INVALIDATION_RECONCILE_FAILED',
+      `${invalidation.error?.code ?? 'UNKNOWN'}: ${invalidation.error?.message ?? ''}`,
+      resolved.taskId
+    );
+  }
   const routed = routeOrchestration(taskRef, options);
   if (!routed.next) return routed;
   const next = routed.next;

package/lib/task/review-artifacts.ts

@@ -176,19 +176,25 @@ function equalCounts(left: ReviewFindingCounts, right: ReviewFindingCounts): boo
 
 function finalizeReviewSummaryContent(
   content: string,
-  counts: ReviewFindingCounts
+  counts: ReviewFindingCounts,
+  options: { refreshNumericCounts?: boolean } = {}
 ): 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 {
+    if (!options.refreshNumericCounts) 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);
+  if (parsed.summary.countState === 'numeric') {
+    const values = [counts.blocker, counts.major, counts.minor];
+    let ordinal = 0;
+    line = line.replace(/\d+(?=\s*(?:阻塞项|主要|次要|blockers?\b|majors?\b|minors?\b))/gi, () => String(values[ordinal++]));
+  }
   line = line
     .replace(PLACEHOLDERS[0], String(counts.blocker))
     .replace(PLACEHOLDERS[1], String(counts.major))

package/lib/task/review-command.ts

@@ -3,7 +3,7 @@ import type { ReviewFinalizationRequest } from './review-finalization.ts';
 export function parseReviewCommand(args: readonly string[]): ReviewFinalizationRequest & {
   overrideTicket?: string; overrideTarget?: string; overrideScope?: string;
 } {
-  if (!args[0] || args[1] !== 'finalize-summary') throw new Error('task ref and finalize-summary are required');
+  if (!args[0] || !['preflight', 'finalize-summary'].includes(args[1] ?? '')) throw new Error('task ref and a supported review operation are required');
   const values: Record<string, string | boolean> = {};
   const flags = {
     '--stage': 'stage', '--artifact': 'artifact', '--orchestrated': 'orchestrated', '--dry-run': 'dryRun',

package/lib/task/review-finalization.ts

@@ -14,11 +14,14 @@ 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 { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.ts';
 import { readArtifactRecoveryIntent } from './artifact-repair-intent.ts';
 import {
   beginArtifactRecovery,
   commitArtifactRecovery,
+  prepareArtifactRecoveryFinal,
   prepareArtifactRecoveryCommit,
+  reconcileArtifactRecovery,
   recoveryContextFromIntent,
   stageArtifactCandidate
 } from './artifact-recovery.ts';
@@ -36,6 +39,7 @@ type ReviewFinalizationErrorCode =
   | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
   | 'REVIEW_SUMMARY_COUNT_MISMATCH'
   | 'REVIEW_ARTIFACT_STRUCTURE_INVALID'
+  | 'REVIEW_ARTIFACT_QUALIFICATION_INVALID'
   | 'REVIEW_DECISION_DETAIL_INVALID'
   | 'REVIEW_ARTIFACT_CONFLICT'
   | 'REVIEW_PROVENANCE_INVALID'
@@ -73,6 +77,11 @@ type ReviewFinalizationResult = {
   }[];
   error: ReviewFinalizationError | null;
 };
+type ReviewPreflightResult = Omit<ReviewFinalizationResult, 'status' | 'intent' | 'stageStatus'> & {
+  status: 'passed' | 'failed';
+  intent: 'preflight';
+  stageStatus: null;
+};
 type ReviewFileSystem = {
   readFileSync: (file: string) => string;
 };
@@ -118,6 +127,141 @@ function failed(
   };
 }
 
+function preflightFailed(
+  request: ReviewFinalizationRequest,
+  code: ReviewFinalizationErrorCode,
+  message: string,
+  taskId: string | null = null,
+  extra: Partial<ReviewPreflightResult> = {}
+): ReviewPreflightResult {
+  const { status: _status, intent: _intent, stageStatus: _stageStatus, ...finalizationExtra } = extra;
+  return {
+    ...failed(request, code, message, taskId, null, finalizationExtra),
+    status: 'failed',
+    intent: 'preflight',
+    stageStatus: null
+  };
+}
+
+/** Validate and seal a review draft before any finding-ledger write. */
+function preflightReviewSummaryUnlocked(
+  request: ReviewFinalizationRequest,
+  options: ReviewFinalizationOptions = {}
+): ReviewPreflightResult {
+  const stage = request.stage as ReviewStage;
+  const spec = STAGES[stage];
+  if (!spec) return preflightFailed(request, 'REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
+  if (!request.taskRef || !request.artifact) return preflightFailed(request, 'REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return preflightFailed(request, resolved.code, resolved.message, resolved.taskId ?? null);
+  if (resolved.state !== 'active') return preflightFailed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  const parsed = parseArtifactName(request.artifact);
+  if (!parsed || parsed.family !== spec.family) return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${spec.family}`, resolved.taskId);
+  const publicationError = validateArtifactPublication(resolved.taskDir, spec.family, request.artifact);
+  if (publicationError) return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', publicationError.message, resolved.taskId);
+
+  let taskContent: string;
+  let content: string;
+  let recovery: ArtifactRecoveryContext | undefined;
+  try {
+    taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    if (request.recoveryId) {
+      const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
+      if (!intent || intent.recoveryOperationId !== request.recoveryId) return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal', resolved.taskId);
+      if (!['awaiting-preflight-recovery', 'preflight-ready'].includes(intent.state)) return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`, resolved.taskId);
+      recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
+      content = fs.existsSync(recovery.stagingPath)
+        ? fs.readFileSync(recovery.stagingPath, 'utf8')
+        : fs.readFileSync(recovery.formalPath, 'utf8');
+    } else {
+      const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
+      if (!validated.ok) return preflightFailed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
+      content = fs.readFileSync(validated.artifact.path, 'utf8');
+      const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
+      if (intent?.state === 'preflight-ready') recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
+      if (intent?.state === 'consumed') return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'review artifact was already finalized', resolved.taskId);
+    }
+  } catch (error) { return preflightFailed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId); }
+
+  if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) return preflightFailed(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: parsed.round, artifact: request.artifact, role: 'reviewer' },
+    dryRun: request.dryRun
+  }, { repoRoot: options.repoRoot });
+  if (!execution.ok) return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`, resolved.taskId);
+
+  const artifactSha256 = sha256Content(content);
+  const semanticDigest = canonicalSemanticDigest(content);
+  const detail = inspectDecisionDetailDuplicates(content);
+  const structure = inspectArtifactContract(content, getArtifactSchema(spec.family)!);
+  const expected = expectedQualificationRelations(taskContent, spec.family);
+  if (!expected.ok) return preflightFailed(request, 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', `${expected.code}: ${expected.message}`, resolved.taskId, { artifactSha256, semanticDigest });
+  const qualification = validateQualificationAudit(taskContent, content, {
+    family: spec.family,
+    artifact: request.artifact,
+    expectedUpstreamRelations: expected.relations
+  });
+  const qualificationError = qualification.ok ? null : qualification;
+  if (!detail.ok || !structure.ok || qualificationError) {
+    if (!recovery && !request.dryRun) {
+      try {
+        recovery = beginArtifactRecovery({
+          taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
+          requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
+        }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
+      } catch (error) { return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId); }
+    }
+    const diagnostics = [
+      ...(!detail.ok ? [`${detail.code}: ${detail.message}`] : []),
+      ...structure.diagnostics.map((item) => `${item.code}: ${item.message}`),
+      ...(qualificationError ? [`${qualificationError.code}: ${qualificationError.message}`] : [])
+    ].join('; ');
+    return preflightFailed(request, !detail.ok ? 'REVIEW_DECISION_DETAIL_INVALID' : !structure.ok ? 'REVIEW_ARTIFACT_STRUCTURE_INVALID' : 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', diagnostics, resolved.taskId, {
+      artifactSha256, semanticDigest,
+      ...(recovery ? { recovery: recoveryInfo(recovery) } : {})
+    });
+  }
+  if (request.dryRun || recovery && readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact)?.state === 'preflight-ready') {
+    return {
+      ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, ...(recovery ? { recovery: recoveryInfo(recovery) } : {}) }),
+      status: 'passed', changed: false, error: null
+    };
+  }
+  try {
+    recovery ??= beginArtifactRecovery({
+      taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
+      requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
+    }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
+    const staged = stageArtifactCandidate(recovery, Buffer.from(content, 'utf8'), { lockAlreadyHeld: options.lockAlreadyHeld });
+    prepareArtifactRecoveryCommit(recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: options.lockAlreadyHeld });
+    return {
+      ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, recovery: recoveryInfo(recovery) }),
+      status: 'passed', changed: false, error: null
+    };
+  } catch (error) { return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId, { artifactSha256, semanticDigest }); }
+}
+
+function preflightReviewSummary(
+  request: ReviewFinalizationRequest,
+  options: ReviewFinalizationOptions = {}
+): ReviewPreflightResult {
+  if (request.dryRun || options.lockAlreadyHeld) return preflightReviewSummaryUnlocked(request, options);
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return preflightReviewSummaryUnlocked(request, options);
+  try {
+    return withTaskExecutionLock(
+      resolved.repoRoot,
+      resolved.taskId,
+      'task-review.preflight',
+      () => preflightReviewSummaryUnlocked(request, { ...options, lockAlreadyHeld: true })
+    );
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
+  }
+}
+
 type ReviewSummaryCandidatePreparation = Readonly<{
   result: ReviewFinalizationResult;
   content: string;
@@ -125,6 +269,15 @@ type ReviewSummaryCandidatePreparation = Readonly<{
   lockAlreadyHeld?: boolean;
 }>;
 
+function recoveryInfo(recovery: ArtifactRecoveryContext): NonNullable<ReviewFinalizationResult['recovery']> {
+  return {
+    recoveryId: recovery.recoveryId,
+    candidatePath: recovery.stagingPath,
+    baselineSha256: recovery.baselineSha256,
+    baselineSemanticDigest: recovery.baselineSemanticDigest
+  };
+}
+
 /** Prepare domain validation, summary bytes and provenance before any publication. */
 function prepareReviewSummaryCandidate(
   request: ReviewFinalizationRequest,
@@ -158,7 +311,7 @@ function prepareReviewSummaryCandidate(
     try {
       const intent = readArtifactRecoveryIntent(resolved.repoRoot, taskId!, spec.family, request.artifact);
       if (!intent || intent.recoveryOperationId !== request.recoveryId) return reject('REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal');
-      if (!['awaiting-recovery', 'finalize-ready', 'commit-started'].includes(intent.state)) return reject('REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`);
+      if (!['awaiting-preflight-recovery', 'preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready', 'commit-started'].includes(intent.state)) return reject('REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`);
       recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
       artifactContent = fs.existsSync(recovery.stagingPath)
         ? fs.readFileSync(recovery.stagingPath, 'utf8')
@@ -171,11 +324,15 @@ function prepareReviewSummaryCandidate(
   let repairIntent;
   try { repairIntent = readArtifactRecoveryIntent(resolved.repoRoot, taskId!, spec.family, request.artifact); }
   catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error), digests); }
-  if (repairIntent?.state === 'passed' || repairIntent?.state === 'consumed') {
+  if (repairIntent?.state === 'consumed') {
     if (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest) {
       return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', digests);
     }
   }
+  if (repairIntent?.state === 'passed'
+    && (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest)) {
+    repairIntent = undefined;
+  }
   if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) {
     return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`);
   }
@@ -220,9 +377,17 @@ function prepareReviewSummaryCandidate(
       ...(recovery ? { recovery } : {})
     };
   }
-  const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
+  const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts, {
+    refreshNumericCounts: Boolean(request.recoveryId && recovery)
+  });
   if (!transformed.ok) return reject(transformed.code, transformed.message);
   const finalDigests = { artifactSha256: sha256Content(transformed.content), semanticDigest: canonicalSemanticDigest(transformed.content) };
+  if (!recovery && repairIntent?.state === 'commit-started') {
+    if (repairIntent.finalArtifactSha256 !== finalDigests.artifactSha256 || repairIntent.finalSemanticDigest !== finalDigests.semanticDigest) {
+      return reject('REVIEW_PROVENANCE_INVALID', 'formal review artifact does not match the interrupted recovery journal', finalDigests);
+    }
+    recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, repairIntent);
+  }
   if (!recovery && (repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')) {
     if (transformed.changed) return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact requires changes after its completed recovery was consumed', finalDigests);
     return {
@@ -260,21 +425,43 @@ function prepareReviewSummaryCandidate(
 
 function commitReviewSummaryProvenance(
   prepared: ReviewSummaryCandidatePreparation,
-  repoRoot: string
+  repoRoot: string,
+  options: Readonly<{ afterPublish?: () => void }> = {}
 ): ReviewFinalizationResult {
   if (prepared.result.status === 'failed' || !prepared.recovery) return prepared.result;
   try {
     const intent = readArtifactRecoveryIntent(prepared.recovery.repoRoot, prepared.recovery.taskId, prepared.recovery.family, prepared.recovery.artifact);
     if (!intent) throw new Error('ARTIFACT_RECOVERY_INTENT_MISSING');
     let committed;
-    if (intent.state === 'finalize-ready' || intent.state === 'commit-started') {
-      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
-    } else {
+    if (intent.state === 'passed' || intent.state === 'consumed') {
+      return {
+        ...prepared.result,
+        status: 'no-op',
+        changed: false,
+        artifactSha256: intent.finalArtifactSha256,
+        semanticDigest: intent.finalSemanticDigest,
+        error: null
+      };
+    } else if (intent.state === 'commit-started') {
+      const reconciled = reconcileArtifactRecovery(prepared.recovery, {
+        lockAlreadyHeld: prepared.lockAlreadyHeld,
+        afterPublish: options.afterPublish
+      });
+      committed = reconciled.intent;
+    } else if (intent.state === 'awaiting-preflight-recovery') {
       const staged = stageArtifactCandidate(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
       prepareArtifactRecoveryCommit(prepared.recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: prepared.lockAlreadyHeld });
       committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+    } else if (intent.state === 'preflight-ready' || intent.state === 'preflight-commit-started') {
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+    }
+    if (committed?.state === 'preflight-passed' || intent.state === 'preflight-passed') {
+      prepareArtifactRecoveryFinal(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+    } else if (intent.state === 'full-finalizer-ready') {
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
     }
-    if (committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed.state}'`);
+    if (!committed || committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed?.state ?? intent.state}'`);
     return {
       ...prepared.result,
       artifactSha256: committed.finalArtifactSha256,
@@ -282,6 +469,7 @@ function commitReviewSummaryProvenance(
       error: null
     };
   } catch (error) {
+    if (error instanceof Error && error.message.startsWith('TASK_WORKFLOW_FAULT_INJECTED:')) throw error;
     return { ...prepared.result, status: 'failed', error: {
       code: 'REVIEW_RECOVERY_COMMIT_FAILED', message: `cannot publish review candidate: ${String(error)}`
     } };
@@ -335,12 +523,13 @@ function finalizeReviewSummary(
   }
 }
 
-export { finalizeReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
+export { finalizeReviewSummary, preflightReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 export type {
   ReviewFinalizationError,
   ReviewFinalizationErrorCode,
   ReviewFinalizationOptions,
   ReviewFinalizationRequest,
   ReviewFinalizationResult,
+  ReviewPreflightResult,
   ReviewSummaryCandidatePreparation
 };

package/lib/{host-control → task}/secure-fs.ts

@@ -1,6 +1,6 @@
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createHash } from 'node:crypto';
 
 const NO_FOLLOW = fs.constants.O_NOFOLLOW ?? 0;
 const DIRECTORY = fs.constants.O_DIRECTORY ?? 0;
@@ -25,11 +25,8 @@ function conflict(message: string): never {
 }
 
 function sameStat(left: fs.BigIntStats, right: fs.BigIntStats): boolean {
-  return left.dev === right.dev
-    && left.ino === right.ino
-    && left.size === right.size
-    && left.mtimeNs === right.mtimeNs
-    && left.ctimeNs === right.ctimeNs;
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size
+    && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
 }
 
 function assertNoSymlinkAncestors(candidate: string): void {
@@ -43,25 +40,15 @@ function assertNoSymlinkAncestors(candidate: string): void {
   }
 }
 
-export async function readStableFile(
-  candidate: string,
-  options: Readonly<{ maxBytes: number; expectedSha256?: string }>
-): Promise<StableFile> {
+export async function readStableFile(candidate: string, options: Readonly<{ maxBytes: number; expectedSha256?: string }>): Promise<StableFile> {
   return readStableFileSync(candidate, options);
 }
 
-/** Shared bounded reader for synchronous domain commands and async workflow callers. */
-export function readStableFileSync(
-  candidate: string,
-  options: Readonly<{ maxBytes: number; expectedSha256?: string }>
-): StableFile {
-  if (!path.isAbsolute(candidate)) {
-    conflict('candidate path must be absolute and terminal');
-  }
+export function readStableFileSync(candidate: string, options: Readonly<{ maxBytes: number; expectedSha256?: string }>): StableFile {
+  if (!path.isAbsolute(candidate)) conflict('candidate path must be absolute and terminal');
   assertNoSymlinkAncestors(candidate);
   let descriptor: number | undefined;
   try {
-    // O_NONBLOCK lets fstat reject a FIFO even when it has no writer.
     descriptor = fs.openSync(candidate, fs.constants.O_RDONLY | NO_FOLLOW | (fs.constants.O_NONBLOCK ?? 0));
     const before = fs.fstatSync(descriptor, { bigint: true });
     if (!before.isFile()) conflict('candidate is not a regular file');
@@ -76,16 +63,12 @@ export function readStableFileSync(
     const after = fs.fstatSync(descriptor, { bigint: true });
     if (!sameStat(before, after)) conflict('candidate identity or metadata changed during read');
     const sha256 = createHash('sha256').update(bytes).digest('hex');
-    if (options.expectedSha256 !== undefined && sha256 !== options.expectedSha256) {
-      conflict('candidate digest does not match the expected digest');
-    }
+    if (options.expectedSha256 !== undefined && sha256 !== options.expectedSha256) conflict('candidate digest does not match the expected digest');
     return { bytes, sha256, stat: after };
   } catch (error) {
     if (error instanceof SecureFileError) throw error;
     const code = (error as NodeJS.ErrnoException).code;
-    if (code === 'ELOOP' || code === 'ENOTSUP' || code === 'EINVAL') {
-      conflict('candidate terminal is not a stable non-symlink file');
-    }
+    if (code === 'ELOOP' || code === 'ENOTSUP' || code === 'EINVAL') conflict('candidate terminal is not a stable non-symlink file');
     throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', error instanceof Error ? error.message : String(error));
   } finally {
     if (descriptor !== undefined) fs.closeSync(descriptor);
@@ -99,18 +82,14 @@ export async function writeAtomicFile(target: string, bytes: Buffer, mode = 0o60
     let stat: fs.Stats;
     try { stat = await fs.promises.lstat(current); }
     catch { throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is missing'); }
-    if (!stat.isDirectory() || stat.isSymbolicLink()) {
-      throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is not a real directory');
-    }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is not a real directory');
     const next = path.dirname(current);
     if (next === current) break;
     current = next;
   }
   try {
     const existing = await fs.promises.lstat(target);
-    if (existing.isSymbolicLink() || !existing.isFile()) {
-      throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative target is not a regular file');
-    }
+    if (existing.isSymbolicLink() || !existing.isFile()) throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative target is not a regular file');
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
   }
@@ -123,7 +102,6 @@ export async function writeAtomicFile(target: string, bytes: Buffer, mode = 0o60
     await handle.chmod(mode);
     await handle.close();
     handle = undefined;
-    // Check after all asynchronous preparation; keep the final check/rename adjacent.
     if (expectedSha256 !== undefined) readStableFileSync(target, { maxBytes: 1024 * 1024, expectedSha256 });
     fs.renameSync(temporary, target);
     const directory = await fs.promises.open(parent, fs.constants.O_RDONLY | DIRECTORY);

package/lib/task/verification-engine.ts

@@ -44,6 +44,7 @@ import { validateQualificationAudit } from "./qualification-audit.ts";
 import { getArtifactSchema } from "./artifact-schema.ts";
 import { inspectArtifactContract } from "./artifact-operations.ts";
 import type { VerificationShared } from "./verification-types.ts";
+import { normalizeVerificationRecord } from './gate-policy.ts';
 import { manualValidationFinalSummaryProjectionMatches } from "./manual-validation-receipt.ts";
 import { readManualValidationCompletion } from "./manual-validation-completion.ts";
 import { sha256File } from "./artifact-receipts.ts";
@@ -1392,11 +1393,11 @@ function interpolate(template: any, taskDir: any, artifactFile: any): any {
 }
 
 function summarizeGate(checks: any): any {
-  if (checks.some((check: any) => check.status === "blocked")) {
+  if (checks.some((check: any) => check.effectiveStatus === "blocked")) {
     return "blocked";
   }
 
-  if (checks.some((check: any) => check.status === "fail")) {
+  if (checks.some((check: any) => check.effectiveStatus === "fail")) {
     return "fail";
   }
 
@@ -1405,9 +1406,9 @@ function summarizeGate(checks: any): any {
 
 function summarizeChecks(checks: any): any {
   const counts = {
-    pass: checks.filter((check: any) => check.status === "pass").length,
-    fail: checks.filter((check: any) => check.status === "fail").length,
-    blocked: checks.filter((check: any) => check.status === "blocked").length
+    pass: checks.filter((check: any) => check.effectiveStatus === "pass").length,
+    fail: checks.filter((check: any) => check.effectiveStatus === "fail").length,
+    blocked: checks.filter((check: any) => check.effectiveStatus === "blocked").length
   };
 
   if (counts.blocked > 0) {
@@ -1422,7 +1423,7 @@ function buildAction(gate: any, checks: any): any {
     return "All declared checks passed";
   }
 
-  const firstFailure = checks.find((check: any) => check.status !== "pass");
+  const firstFailure = checks.find((check: any) => check.effectiveStatus !== "pass");
   if (!firstFailure) {
     return "Review validation output";
   }
@@ -1484,16 +1485,16 @@ async function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks:
     const checks = [];
     for (const [type, checkConfig] of Object.entries(verifyConfig.checks || {})) {
       if (checkConfig === null) continue;
-      const result = await runCheck(type, {
+      const result = normalizeVerificationRecord(await runCheck(type, {
         mode,
         skillName,
         taskDir: path.resolve(taskDir),
         artifactFile,
         repositoryRoot: repoRoot,
         config: checkConfig
-      }, shared);
-      checks.push(result);
-      if (result.status === "blocked") break;
+      }, shared));
+      checks.push(...(result.subchecks?.map(normalizeVerificationRecord) ?? [result]));
+      if (checks.at(-1)?.effectiveStatus === "blocked") break;
     }
     const gate = summarizeGate(checks);
     return { gate, skill: skillName, checks, summary: summarizeChecks(checks), action: buildAction(gate, checks) };
@@ -1502,15 +1503,24 @@ async function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks:
   const config = (verifyConfig.checks || {})[type];
   if (config === undefined) return { skill: skillName, ...failResult(type, `Unknown check type '${type}' for skill '${skillName}'.`) };
   if (config === null) return { skill: skillName, ...passResult(type, `Check '${type}' is disabled for skill '${skillName}'.`) };
-  return {
-    skill: skillName,
-    ...await runCheck(type, {
+  const result = normalizeVerificationRecord(await runCheck(type, {
       skillName,
       taskDir: path.resolve(taskDir),
       artifactFile,
       repositoryRoot: repoRoot,
       config
-    }, shared)
+    }, shared));
+  if (!result.subchecks?.length) return { skill: skillName, ...result };
+  const checks = result.subchecks.map(normalizeVerificationRecord);
+  const gate = summarizeGate(checks);
+  return {
+    skill: skillName,
+    ...result,
+    status: gate,
+    effectiveStatus: gate,
+    reason: gate === 'pass' ? 'OK' : checks.find((check: any) => check.effectiveStatus !== 'pass')?.reason ?? 'CHECK_FAILED',
+    action: buildAction(gate, checks),
+    checks
   };
 }
 

package/lib/task/verification-types.ts

@@ -20,6 +20,13 @@ type VerificationCheckResult = {
   message: string;
   fail_type?: string;
   warnings?: string[];
+  checkId?: string;
+  classification?: 'hard' | 'soft' | 'info';
+  effectiveStatus?: VerificationStatus;
+  reason?: string;
+  action?: string;
+  dependsOn?: string;
+  subchecks?: VerificationCheckResult[];
 };
 type VerificationContext = {
   skillName: string;