@fitlab-ai/agent-infra 0.9.7 → 0.9.9

package/lib/task/review-finalization.ts

@@ -11,6 +11,8 @@ 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';
+import { allowsManualOverride } from './guard-override.ts';
+import type { ManualOverrideCapability } from './guard-override.ts';
 
 type ReviewFinalizationErrorCode =
   | ResolveTaskRefErrorCode
@@ -62,6 +64,8 @@ type ReviewFinalizationOptions = {
   repoRoot?: string;
   randomSuffix?: () => string;
   fileSystem?: Partial<ReviewFileSystem>;
+  manualOverride?: ManualOverrideCapability;
+  lockAlreadyHeld?: boolean;
 };
 
 const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code'; action: string }> = {
@@ -127,7 +131,7 @@ function finalizeReviewSummaryUnlocked(
   }
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(request, resolved.code, resolved.message, resolved.taskId);
-  if (resolved.state !== 'active') {
+  if (resolved.state !== 'active' && !allowsManualOverride(options.manualOverride, 'review-finalization', 'TASK_STATE_MISMATCH')) {
     return failed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   }
   const parsedArtifact = parseArtifactName(request.artifact);
@@ -275,7 +279,7 @@ function finalizeReviewSummary(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
 ): ReviewFinalizationResult {
-  if (request.dryRun) return finalizeReviewSummaryUnlocked(request, options);
+  if (request.dryRun || options.lockAlreadyHeld) return finalizeReviewSummaryUnlocked(request, options);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, options);
   try {

package/lib/task/short-id.ts

@@ -201,6 +201,10 @@ type RegistrySchema = {
   ids: Record<string, string>;
 };
 
+type ShortIdRegistryInspection =
+  | { status: 'valid'; shortIds: Map<string, string> }
+  | { status: 'missing' | 'invalid'; error: { code: string; message: string } };
+
 type ShortIdMutationEffect = 'alloc' | 'release' | 'none';
 type ShortIdMutationResult = {
   effect: 'allocated' | 'released' | 'unchanged';
@@ -446,6 +450,64 @@ function loadShortIdByTaskId(repoRoot: string): Map<string, string> {
   return map;
 }
 
+function inspectShortIdRegistry(repoRoot: string): ShortIdRegistryInspection {
+  const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', REGISTRY_NAME);
+  if (!fs.existsSync(registryPath)) {
+    return {
+      status: 'missing',
+      error: {
+        code: 'SHORT_ID_REGISTRY_NOT_FOUND',
+        message: 'canonical short-id registry is missing'
+      }
+    };
+  }
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(registryPath, 'utf8');
+  } catch {
+    return {
+      status: 'invalid',
+      error: {
+        code: 'SHORT_ID_REGISTRY_READ_FAILED',
+        message: 'canonical short-id registry is unreadable'
+      }
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {
+      status: 'invalid',
+      error: {
+        code: 'SHORT_ID_REGISTRY_INVALID_JSON',
+        message: 'canonical short-id registry contains invalid JSON'
+      }
+    };
+  }
+
+  try {
+    const registry = validateRegistry(parsed, registryPath, configuredShortIdLength(repoRoot));
+    const shortIds = new Map<string, string>();
+    for (const [key, taskId] of Object.entries(registry.ids)) shortIds.set(taskId, key);
+    return { status: 'valid', shortIds };
+  } catch (error) {
+    return {
+      status: 'invalid',
+      error: {
+        code: typeof (error as { code?: unknown }).code === 'string'
+          ? (error as { code: string }).code
+          : 'SHORT_ID_REGISTRY_INVALID_SCHEMA',
+        message: (error as { code?: unknown }).code === 'SHORT_ID_REGISTRY_DUPLICATE_TASK'
+          ? 'canonical short-id registry contains duplicate task entries'
+          : 'canonical short-id registry has invalid schema'
+      }
+    };
+  }
+}
+
 /**
  * Resolve a branch to its active-task short id (`NN`), or `null` when no
  * active task is bound to that branch.
@@ -485,6 +547,7 @@ export {
   resolveShortIdReadOnly,
   lookupShortIdByBranch,
   loadShortIdByTaskId,
+  inspectShortIdRegistry,
   configuredShortIdLength,
   mutateShortIdRegistry,
   executeShortIdCommand
@@ -497,5 +560,6 @@ export type {
   ShortIdMutationEffect,
   ShortIdMutationResult,
   ShortIdCommandRequest,
-  ShortIdCommandResult
+  ShortIdCommandResult,
+  ShortIdRegistryInspection
 };

package/lib/task/task-execution-lock.ts

@@ -272,6 +272,7 @@ function withTaskExecutionLock<T>(
     return callback();
   } catch (error) {
     if (error instanceof TaskExecutionLockError) throw error;
+    if (error instanceof Error && error.name === 'OrchestrationStateError') throw error;
     throw new TaskExecutionLockError(
       'ORCHESTRATION_LOCK_FAILED',
       'lifecycle task lock operation failed',
@@ -294,5 +295,13 @@ function withTaskExecutionLock<T>(
   }
 }
 
-export { TaskExecutionLockError, lockKey, mapLinkError, withTaskExecutionLock };
+function withRepositoryMutationLock<T>(
+  repoRoot: string,
+  callback: () => T,
+  options: TaskExecutionLockOptions = {}
+): T {
+  return withTaskExecutionLock(repoRoot, '__repository_mutation__', 'repository-mutation', callback, options);
+}
+
+export { TaskExecutionLockError, lockKey, mapLinkError, withRepositoryMutationLock, withTaskExecutionLock };
 export type { LinkDisposition, LinkOperation, TaskExecutionLockErrorCode, TaskExecutionLockOptions, TaskExecutionLockOwner };

package/lib/task/verification-engine.ts

@@ -27,6 +27,7 @@ import type { LedgerRow } from "./ledger.ts";
 import { equalCounts, parseReviewSummary } from "./review-artifacts.ts";
 import { loadVerificationConfig } from "./verification-config.ts";
 import { snapshotReview } from "../git/review-snapshot.ts";
+import { OrchestrationStateError, readRun } from "./orchestration.ts";
 
 const TASK_ENUMS = {
   type: ["feature", "bugfix", "refactor", "docs", "chore"],
@@ -123,6 +124,8 @@ function runCheck(type: any, context: any, shared: any): any {
       return checkReviewFact(context);
     case "post-review-commit":
       return checkPostReviewCommit(context);
+    case "required-pr-delivery":
+      return checkRequiredPrDelivery(context);
     case "orchestration-state":
       return checkOrchestrationState(context);
     case "orchestration-evidence":
@@ -142,40 +145,19 @@ function runCheck(type: any, context: any, shared: any): any {
   }
 }
 
-function isFailClosedLegacyPause(run: any): boolean {
-  if (
-    run.schemaVersion !== 1
-    || run.status !== 'paused'
-    || run.pause?.recoverable !== false
-    || !exactText(run.pause?.message)
-    || !Array.isArray(run.receipts)
-  ) {
-    return false;
-  }
-  if (run.pause.code === 'ORCHESTRATION_HISTORICAL_EFFORT_UNVERIFIED') {
-    return run.receipts.length > 0 && run.pendingDelegation === null;
-  }
-  if (run.pause.code === 'ORCHESTRATION_DELEGATION_BUSY') {
-    return run.pendingDelegation != null && run.pendingDelegation.status !== 'sealed';
-  }
-  return false;
-}
-
 function checkOrchestrationState({ taskDir }: any): any {
   const file = path.join(taskDir, 'orchestration.json');
   const stat = safeStat(file);
   if (!stat?.isFile()) return failResult('orchestration-state', 'orchestration.json is missing');
   let run: any;
   try {
-    run = JSON.parse(fs.readFileSync(file, 'utf8'));
+    run = readRun(taskDir);
   } catch (error) {
-    return failResult('orchestration-state', `Invalid orchestration.json: ${String(error)}`);
-  }
-  if (isFailClosedLegacyPause(run)) {
-    return passResult('orchestration-state', 'Legacy orchestration run is safely paused');
+    const message = error instanceof OrchestrationStateError ? error.message : String(error);
+    return failResult('orchestration-state', `Invalid orchestration.json: ${message}`);
   }
-  if (![2, 3].includes(run.schemaVersion) || !['paused', 'completed'].includes(run.status)) {
-    return failResult('orchestration-state', `Expected paused or completed run, received '${run.status}'`);
+  if (!run || !['paused', 'completed'].includes(run.status)) {
+    return failResult('orchestration-state', `Expected paused or completed run, received '${run?.status ?? 'missing'}'`);
   }
   if (run.status === 'paused' && (!run.pause?.code || !run.pause?.message)) {
     return failResult('orchestration-state', 'Paused run requires a stable pause code and message');
@@ -242,12 +224,10 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
   if (!stat?.isFile()) return failResult('orchestration-evidence', 'orchestration.json is missing');
   let run: any;
   try {
-    run = JSON.parse(fs.readFileSync(file, 'utf8'));
+    run = readRun(taskDir);
   } catch (error) {
-    return failResult('orchestration-evidence', `Invalid orchestration.json: ${String(error)}`);
-  }
-  if (isFailClosedLegacyPause(run)) {
-    return passResult('orchestration-evidence', 'Legacy orchestration evidence is preserved in a fail-closed pause');
+    const message = error instanceof OrchestrationStateError ? error.message : String(error);
+    return failResult('orchestration-evidence', `Invalid orchestration.json: ${message}`);
   }
   const policy = run.modelPolicy;
   if (
@@ -269,18 +249,11 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
     return failResult('orchestration-evidence', 'Run model policy source or recovery history is invalid');
   }
   for (const recovery of run.recoveryHistory) {
-    const validModelRecovery = recovery.code === 'MODEL_POLICY_SUPPLEMENTED'
-      && recovery.previousSchemaVersion === 1
-      && recovery.receiptCount === 0
-      && recovery.pendingDelegation === false
-      && exactText(recovery.recoveredAt)
-      && recovery.policySource;
     const guards = recovery.guards;
-    const validCapabilityRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED'
-      && recovery.previousSchemaVersion === 2
+    const validClaudeCodeRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED'
       && recovery.previousStatus === 'paused'
       && recovery.previousPause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
-      && recovery.client === 'codex'
+      && recovery.client === 'claude-code'
       && recovery.resultingStatus === 'running'
       && exactText(recovery.recoveredAt)
       && guards?.stepCount === 0
@@ -289,9 +262,8 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
       && guards?.receiptCount === 0
       && guards?.pendingDelegation === false
       && guards?.commitAuthorizationUnused === true
-      && guards?.completionEvidenceAbsent === true
-      && guards?.commitIntentAbsent === true;
-    if (!validModelRecovery && !validCapabilityRecovery) {
+      && guards?.completionEvidenceAbsent === true;
+    if (!validClaudeCodeRecovery) {
       return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
     }
   }
@@ -322,40 +294,76 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
     }
     const activated = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
     if (activated) {
-      if (!exactText(receipt.actualModel)) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+      const isClaudeCode = receipt.client === 'claude-code';
+      if (!isClaudeCode) {
+        if (!exactText(receipt.actualModel)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+        }
+        if (!exactText(receipt.actualReasoningEffort)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+        }
       }
-      if (!exactText(receipt.actualReasoningEffort)) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+      // parentId/childId 校验对所有 client 保持统一（不新增分支）；spawnMode 检查按 client 判断
+      if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid delegation identity`);
       }
-      if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId || receipt.spawnMode !== 'fresh') {
+      if (!isClaudeCode && receipt.spawnMode !== 'fresh') {
         return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid fresh delegation identity`);
       }
-      if (receipt.actualModel !== receipt.requestedModel && !exactText(receipt.modelFallbackReason)) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
-      }
-      if (receipt.actualModel === receipt.requestedModel && receipt.modelFallbackReason !== null) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
+      if (receipt.actualModel != null && receipt.actualModel !== receipt.requestedModel) {
+        if (!isClaudeCode && !exactText(receipt.modelFallbackReason)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
+        }
       }
       if (
-        receipt.actualReasoningEffort !== receipt.requestedReasoningEffort
-        && !exactText(receipt.reasoningEffortFallbackReason)
+        (receipt.actualModel == null || receipt.actualModel === receipt.requestedModel)
+        && receipt.modelFallbackReason !== null
       ) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
+      }
+      if (receipt.actualReasoningEffort != null && receipt.actualReasoningEffort !== receipt.requestedReasoningEffort) {
+        if (!isClaudeCode && !exactText(receipt.reasoningEffortFallbackReason)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+        }
       }
       if (
-        receipt.actualReasoningEffort === receipt.requestedReasoningEffort
+        (receipt.actualReasoningEffort == null || receipt.actualReasoningEffort === receipt.requestedReasoningEffort)
         && receipt.reasoningEffortFallbackReason !== null
       ) {
         return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated reasoning-effort fallback reason`);
       }
       if (receipt.client === 'codex') {
+        const activatedCodex = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
         const host = receipt.hostEvidence;
+        const provenance = receipt.lifecycleProvenance;
         if (
-          host?.kind !== 'codex-lifecycle-v1'
-          || !exactText(host.hookDefinitionHash)
-          || !Number.isSafeInteger(host.startRevision)
-          || host.startRevision < 1
+          !provenance
+          || (activatedCodex && (
+            host?.kind !== 'codex-lifecycle-v2'
+            || host.protocolVersion !== provenance.protocolVersion
+            || host.packageVersion !== provenance.packageVersion
+            || host.internalExecutableBuildHash !== provenance.internalExecutableBuildHash
+            || host.lifecycleContractHash !== provenance.lifecycleContractHash
+            || host.hookDefinitionHash !== provenance.hookDefinitionHash
+            || host.hookSource !== provenance.hookSource
+            || host.hookSourcePathDigest !== provenance.hookSourcePathDigest
+            || host.hookSourceHash !== provenance.hookSourceHash
+            || host.capabilitySessionId !== provenance.capabilitySessionId
+            || receipt.parentId !== provenance.capabilitySessionId
+            || host.capabilityTurnId !== provenance.capabilityTurnId
+            || host.controllerInstanceDigest !== provenance.controllerInstanceDigest
+            || host.controlGeneration !== provenance.controlGeneration
+            || host.spawnToolUseId === provenance.capabilityToolUseId
+            || !exactText(host.spawnToolUseId)
+            || !Number.isFinite(Date.parse(host.spawnObservedAt ?? ''))
+            || !Number.isFinite(Date.parse(receipt.spawnDispatchedAt ?? ''))
+            || !Number.isFinite(Date.parse(receipt.activationDeadlineAt ?? ''))
+            || Date.parse(host.spawnObservedAt ?? '') < Date.parse(receipt.spawnDispatchedAt ?? '')
+            || Date.parse(host.spawnObservedAt ?? '') > Date.parse(receipt.activationDeadlineAt ?? '')
+            || !exactText(host.hookDefinitionHash)
+            || !Number.isSafeInteger(host.startRevision)
+            || host.startRevision < 1
+          ))
         ) {
           return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid Codex start evidence`);
         }
@@ -484,6 +492,63 @@ function checkTaskMeta({ taskDir, config }: any): any {
   );
 }
 
+function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }: any): any {
+  const task = loadTask(taskDir);
+  if (!task.ok) return failResult('required-pr-delivery', task.message);
+  let projectConfig: any = {};
+  try {
+    const file = path.join(repositoryRoot, '.agents', '.airc.json');
+    if (safeStat(file)?.isFile()) projectConfig = JSON.parse(fs.readFileSync(file, 'utf8')) as any;
+  } catch {
+    return failResult('required-pr-delivery', 'Project configuration is invalid');
+  }
+  const flow = projectConfig.prFlow;
+  const status = String(task.metadata.pr_status || 'pending');
+  const prNumber = parsePrNumber(task.metadata.pr_number);
+  if (flow === 'disabled') return passResult('required-pr-delivery', 'Pull request delivery is disabled by project policy');
+  if (flow === 'required' && (status !== 'created' || prNumber === null)) {
+    return failResult('required-pr-delivery', 'Project policy requires a bound pull request before completion');
+  }
+  if (flow !== 'required' && status === 'pending') {
+    return failResult('required-pr-delivery', 'Pull request delivery is pending; create a PR or explicitly skip it');
+  }
+  if (status === 'created' && prNumber === null) {
+    return failResult('required-pr-delivery', 'Task claims a created pull request without a valid pr_number');
+  }
+  if (flow === 'required') {
+    if (mode === 'gate') {
+      return passResult('required-pr-delivery', 'Bound pull request shape is valid; merged-state inspection is reserved for hard preflight');
+    }
+    const inspected = inspectPlatformPullRequest(task.metadata.id, { cwd: repositoryRoot });
+    if (inspected.status === 'blocked') {
+      return blockedResult(
+        'required-pr-delivery',
+        inspected.error?.message || 'Unable to inspect the required pull request',
+        inspected.error?.code || 'PR_INSPECTION_BLOCKED'
+      );
+    }
+    const pullRequest = inspected.pullRequest;
+    const repository = inspected.platform.repository?.toLowerCase() || '';
+    const taskBranch = String(task.metadata.branch || '').trim();
+    if (inspected.status !== 'no-op' || !pullRequest || pullRequest.number !== prNumber) {
+      return failResult('required-pr-delivery', 'Bound pull request identity could not be verified');
+    }
+    if (
+      !repository
+      || pullRequest.repository.toLowerCase() !== repository
+      || pullRequest.base.repository.toLowerCase() !== repository
+      || (taskBranch && pullRequest.head.ref !== taskBranch)
+    ) {
+      return failResult('required-pr-delivery', 'Bound pull request identity does not match the task');
+    }
+    if (pullRequest.state !== 'closed' || !pullRequest.mergedAt || !pullRequest.mergeCommitSha) {
+      return failResult('required-pr-delivery', 'Project policy requires the bound pull request to be merged');
+    }
+    return passResult('required-pr-delivery', `Pull request delivery policy satisfied (merged PR #${prNumber})`);
+  }
+  return passResult('required-pr-delivery', `Pull request delivery policy satisfied (${status})`);
+}
+
 function validateTaskBranch(metadata: any): any {
   if (isBlank(metadata.branch)) {
     return null;
@@ -902,7 +967,7 @@ function checkReviewLedger({ taskDir, config }: any): any {
   }
 
   const stageScope = Array.isArray(config.stage_scope) ? config.stage_scope : null;
-  const maxRounds = Number(resolveReviewSetting(config, "max_handshake_rounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
+  const maxRounds = Number(resolveReviewSetting(config, "maxHandshakeRounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
   const problems = [];
   let inScopeCount = 0;
 
@@ -1574,7 +1639,14 @@ function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: reque
     const checks = [];
     for (const [type, checkConfig] of Object.entries(verifyConfig.checks || {})) {
       if (checkConfig === null) continue;
-      const result = runCheck(type, { skillName, taskDir: path.resolve(taskDir), artifactFile, config: checkConfig }, shared);
+      const result = runCheck(type, {
+        mode,
+        skillName,
+        taskDir: path.resolve(taskDir),
+        artifactFile,
+        repositoryRoot: repoRoot,
+        config: checkConfig
+      }, shared);
       checks.push(result);
       if (result.status === "blocked") break;
     }
@@ -1585,7 +1657,16 @@ function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: reque
   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, ...runCheck(type, { skillName, taskDir: path.resolve(taskDir), artifactFile, config }, shared) };
+  return {
+    skill: skillName,
+    ...runCheck(type, {
+      skillName,
+      taskDir: path.resolve(taskDir),
+      artifactFile,
+      repositoryRoot: repoRoot,
+      config
+    }, shared)
+  };
 }
 
 export { verifyInProcess };

package/lib/task/verification.ts

@@ -7,13 +7,15 @@ import { parseArtifactName } from './artifact-lifecycle.ts';
 import type { ArtifactFamily } from './artifact-lifecycle.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import type { TaskWorkspaceState } from './resolve-ref.ts';
+import { allowsManualOverride } from './guard-override.ts';
+import type { ManualOverrideCapability } from './guard-override.ts';
 
 type VerificationEvent =
   | 'analyze.awaiting-input' | 'analyze.completed'
   | 'review-analysis.completed' | 'plan.completed' | 'review-plan.completed'
   | 'code.completed' | 'review-code.completed' | 'manual-validation.completed' | 'validation-run.completed'
   | 'block-task.completed' | 'cancel-task.completed' | 'commit.completed'
-  | 'complete-task.preflight' | 'complete-task.completed'
+  | 'complete-task.preflight' | 'complete-task.hard-preflight' | 'complete-task.completed'
   | 'create-pr.completed' | 'create-task.completed'
   | 'import-codescan.completed' | 'import-dependabot.completed'
   | 'import-issue.completed' | 'watch-pr.completed'
@@ -48,6 +50,7 @@ type TaskVerificationResult = {
 type VerificationOptions = {
   repoRoot?: string;
   engine?: typeof verifyInProcess;
+  manualOverride?: ManualOverrideCapability;
 };
 
 const gate = (skill: string, expectedState: VerificationSpec['expectedState'], artifactFamily?: ArtifactFamily): VerificationSpec => ({
@@ -66,7 +69,8 @@ const VERIFICATION_CATALOG: Readonly<Record<VerificationEvent, VerificationSpec>
   'block-task.completed': gate('block-task', 'blocked'),
   'cancel-task.completed': gate('cancel-task', 'completed'),
   'commit.completed': gate('commit', 'active'),
-  'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['review-ledger', 'manual-validation', 'post-review-commit', 'platform-sync-preflight'] },
+  'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
+  'complete-task.hard-preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
   'complete-task.completed': gate('complete-task', 'completed'),
   'create-pr.completed': gate('create-pr', 'active'),
   'create-task.completed': gate('create-task', 'active'),
@@ -93,7 +97,7 @@ function verifyTaskEvent(request: { taskRef: string; event: string; artifact?: s
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failure(request, resolved.code, resolved.message, { taskId: resolved.taskId, skill: spec.skill, mode: spec.mode });
   const identity = { taskId: resolved.taskId, taskDir: resolved.taskDir, taskState: resolved.state, skill: spec.skill, mode: spec.mode } as const;
-  if (resolved.state !== spec.expectedState) {
+  if (resolved.state !== spec.expectedState && !allowsManualOverride(options.manualOverride, 'task-verify', 'VERIFY_TASK_STATE_MISMATCH')) {
     return failure(request, 'VERIFY_TASK_STATE_MISMATCH', `event '${request.event}' requires workspace '${spec.expectedState}', received '${resolved.state}'`, identity);
   }
   if (spec.artifactFamily) {
@@ -111,11 +115,22 @@ function verifyTaskEvent(request: { taskRef: string; event: string; artifact?: s
   if (spec.mode === 'gate') {
     const payload = engine({ mode: 'gate', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [], repositoryRoot: resolved.repoRoot }) as Record<string, unknown>;
     const status = payload.gate as 'pass' | 'fail' | 'blocked';
+    if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+      invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, gate: 'pass', humanOverride: 'human-approved', originalGate: status } });
+      return {
+        status: 'pass', changed: false, event: request.event, requestRef: request.taskRef,
+        ...identity, artifact: request.artifact ?? null, invocations, error: null
+      };
+    }
     invocations.push({ status, exitCode: ({ pass: 0, fail: 1, blocked: 2 } as const)[status], payload });
   } else {
     for (const check of spec.checks ?? []) {
       const payload = engine({ mode: 'checks', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [check], repositoryRoot: resolved.repoRoot }) as Record<string, unknown>;
       const status = payload.status as 'pass' | 'fail' | 'blocked';
+      if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+        invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, status: 'pass', humanOverride: 'human-approved', originalStatus: status } });
+        break;
+      }
       invocations.push({ status, exitCode: ({ pass: 0, fail: 1, blocked: 2 } as const)[status], payload });
       if (status !== 'pass') break;
     }

package/lib/task/workflow-warning-intents.ts

@@ -11,6 +11,8 @@ import {
 import type { WorkflowWarning } from './workflow-warnings.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
+import { allowsManualOverride } from './guard-override.ts';
+import { retryHintForWarning, type OperationWarning } from './operation-outcome.ts';
 
 type WarningSeverity = 'IMPORTANT' | 'ACTION_REQUIRED';
 type WarningStatus = 'open' | 'resolved' | 'ignored';
@@ -27,6 +29,12 @@ type WorkflowWarningIntentResult = {
   error: { code: string; message: string } | null;
 };
 
+type FinalizationWarningProjectionResult = Readonly<{
+  status: 'applied' | 'no-op' | 'failed';
+  changed: boolean;
+  error: { code: string; message: string } | null;
+}>;
+
 function failed(intent: WorkflowWarningIntent, code: string, message: string, taskId: string | null = null, entityId: string | null = null): WorkflowWarningIntentResult {
   return { status: 'failed', changed: false, intent: intent.kind, taskId, entityId, before: null, after: null, warnings: [], operations: [], error: { code, message } };
 }
@@ -79,7 +87,8 @@ function rowMutation(row: WorkflowWarning): TaskMutation {
 function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: TaskWriteOptions = {}): WorkflowWarningIntentResult {
   const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(intent, resolved.code, resolved.message, resolved.taskId);
-  if (resolved.state !== 'active') return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  const stateOverride = allowsManualOverride(options.manualOverride, 'workflow-warning', 'TASK_STATE_MISMATCH');
+  if (resolved.state !== 'active' && !stateOverride) return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   let content: string;
   let rows: WorkflowWarning[];
   try {
@@ -125,7 +134,7 @@ function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: Task
   }
 
   const writeResult = writeTask({
-    taskRef: intent.taskRef, expectedState: 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
+    taskRef: intent.taskRef, expectedState: stateOverride ? resolved.state : 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
   }, {
     ...options,
     taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state },
@@ -138,5 +147,53 @@ function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: Task
   };
 }
 
-export { applyWorkflowWarningIntent };
-export type { WarningSeverity, WarningStatus, WorkflowWarningIntent, WorkflowWarningIntentResult };
+function projectFinalizationWarning(
+  taskRef: string,
+  warning: OperationWarning & { status: 'open' | 'resolved'; resolvedAt: string | null },
+  options: TaskWriteOptions = {}
+): FinalizationWarningProjectionResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return { status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } };
+  if (resolved.state !== 'completed') return { status: 'failed', changed: false, error: { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected completed` } };
+  let content: string;
+  let rows: WorkflowWarning[];
+  try {
+    content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    rows = parseWorkflowWarnings(content);
+  } catch (error) {
+    return { status: 'failed', changed: false, error: { code: 'WARNING_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) } };
+  }
+  const metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+  const existing = rows.find((row) => row.step === warning.step && row.code === warning.code && row.target === warning.target);
+  const after: WorkflowWarning = existing
+    ? {
+      ...existing,
+      severity: warning.severity,
+      status: warning.status,
+      message: warning.message,
+      action: retryHintForWarning(warning),
+      resolvedAt: warning.resolvedAt || (warning.status === 'resolved' ? metadata.timestamp : ''),
+      resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+    }
+    : {
+      id: nextWarningId(rows), time: metadata.timestamp, step: warning.step,
+      severity: warning.severity, code: warning.code, status: warning.status,
+      target: warning.target, message: warning.message, action: retryHintForWarning(warning),
+      resolvedAt: warning.resolvedAt || '', resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+    };
+  if (existing && JSON.stringify(existing) === JSON.stringify(after)) return { status: 'no-op', changed: false, error: null };
+  const written = writeTask({
+    taskRef: resolved.taskId,
+    expectedState: 'completed',
+    mutations: [...sectionMutation(content), rowMutation(after)]
+  }, {
+    ...options,
+    taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: 'completed' },
+    metadataProvider: () => metadata
+  });
+  if (written.status === 'failed') return { status: 'failed', changed: false, error: { code: written.error.code, message: written.error.message } };
+  return { status: written.status === 'applied' ? 'applied' : 'no-op', changed: written.changed, error: null };
+}
+
+export { applyWorkflowWarningIntent, projectFinalizationWarning };
+export type { FinalizationWarningProjectionResult, WarningSeverity, WarningStatus, WorkflowWarningIntent, WorkflowWarningIntentResult };

package/lib/task/write.ts

@@ -12,6 +12,8 @@ import type {
   ResolveTaskRefErrorCode,
   TaskWorkspaceState
 } from './resolve-ref.ts';
+import { allowsManualOverride } from './guard-override.ts';
+import type { ManualOverrideCapability } from './guard-override.ts';
 import { mutateTableRow, upsertSection } from './sections.ts';
 import type {
   TableRowDeleteMutation,
@@ -156,6 +158,7 @@ type TaskWriteOptions = {
   metadataProvider?: () => TaskWriteMetadata;
   randomSuffix?: () => string;
   fileSystem?: Partial<TaskFileSystem>;
+  manualOverride?: ManualOverrideCapability;
 };
 
 const DEFAULT_FILE_SYSTEM: TaskFileSystem = {
@@ -241,7 +244,7 @@ function writeTask(request: TaskWriteRequest, options: TaskWriteOptions = {}): T
     taskMdPath: resolved.taskMdPath,
     actualState: resolved.state
   };
-  if (resolved.state !== request.expectedState) {
+  if (resolved.state !== request.expectedState && !allowsManualOverride(options.manualOverride, 'task.write', 'TASK_STATE_MISMATCH')) {
     return failure(
       request,
       identity,