@fitlab-ai/agent-infra 0.9.12 → 0.9.13

package/lib/task/orchestration.ts

@@ -4,8 +4,7 @@ import { randomUUID } from 'node:crypto';
 
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
 import { validateCurrentTaskContract } from './current-contract.ts';
-import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.ts';
-import { inspectArtifactDirectory } from './artifact-lifecycle.ts';
+import { parseReviewSummary } from './review-artifacts.ts';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
 import type { LedgerDocument } from './ledger.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
@@ -53,6 +52,11 @@ import { hasActiveCodexLifecycleEvidence } from '../agent-clients/adapters/codex
 import type { CodexCapabilityProvenanceDetail } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
 import { extractReviewBaseline, extractReviewDiffBase, extractReviewTargetHead, extractReviewedHead } from './review-fingerprint.ts';
 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 type { LifecycleAction, LifecycleFacts } from './capabilities.ts';
 
 type OrchestrationStatus = 'running' | 'paused' | 'completed';
 type ModelPolicySource = Readonly<{
@@ -108,7 +112,7 @@ type OrchestrationRun = Readonly<{
   updatedAt: string;
 }>;
 type OrchestrationNext = Readonly<{
-  action: 'analyze-task' | 'review-analysis' | 'plan-task' | 'review-plan' | 'code-task' | 'review-code' | 'commit';
+  action: 'analyze-task' | 'review-analysis' | 'plan-task' | 'review-plan' | 'code-task' | 'review-code';
   role: DelegationRole;
   stage: DelegationStage;
   round: number;
@@ -561,78 +565,19 @@ function validateSavedCurrentDiffBase(
   return null;
 }
 
-function hasReviewAfterArtifact(taskDir: string, family: string, reviewFamily: string): boolean {
-  const artifact = inspectArtifactDirectory(taskDir, family as 'analysis' | 'plan' | 'code');
-  const review = inspectArtifactDirectory(taskDir, reviewFamily as 'review-analysis' | 'review-plan' | 'review-code');
-  return artifact.status === 'ready'
-    && review.status === 'ready'
-    && artifact.latest !== null
-    && review.reviewedInput?.name === artifact.latest.name;
-}
-
-function latestReviewApproved(taskDir: string, family: 'review-analysis' | 'review-plan' | 'review-code'): { approved: boolean; error: string | null } {
-  const round = highestRound(taskDir, family);
-  if (round === 0) return { approved: false, error: null };
-  let content: string;
-  try { content = fs.readFileSync(path.join(taskDir, artifactName(family, round)), 'utf8'); }
-  catch (error) { return { approved: false, error: String(error) }; }
-  const parsed = parseReviewSummary(content);
-  if (!parsed.ok) return { approved: false, error: `${parsed.code}: ${parsed.message}` };
-  const verdict = resolveCanonicalVerdict(parsed.summary);
-  if (!verdict.ok) return { approved: false, error: `${verdict.code}: ${verdict.message}` };
-  return { approved: verdict.verdict === 'Approved', error: null };
-}
-
-function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedModel' | 'requestedReasoningEffort'> | { error: string } | null {
-  const analysisRound = highestRound(taskDir, 'analysis');
-  const analysisReviewRound = highestRound(taskDir, 'review-analysis');
-  const planRound = highestRound(taskDir, 'plan');
-  const planReviewRound = highestRound(taskDir, 'review-plan');
-  const codeRound = highestRound(taskDir, 'code');
-  const codeReviewRound = highestRound(taskDir, 'review-code');
-  if (analysisRound === 0) {
-    const round = analysisRound + 1;
-    return { action: 'analyze-task', role: 'executor', stage: 'analysis', round, artifact: artifactName('analysis', round) };
-  }
-  if (!hasReviewAfterArtifact(taskDir, 'analysis', 'review-analysis')) {
-    const round = analysisReviewRound + 1;
-    return { action: 'review-analysis', role: 'reviewer', stage: 'review-analysis', round, artifact: artifactName('review-analysis', round) };
-  }
-  const analysisVerdict = latestReviewApproved(taskDir, 'review-analysis');
-  if (analysisVerdict.error) return { error: analysisVerdict.error };
-  if (!analysisVerdict.approved) {
-    const round = analysisRound + 1;
-    return { action: 'analyze-task', role: 'executor', stage: 'analysis', round, artifact: artifactName('analysis', round) };
-  }
-  if (planRound === 0) {
-    const round = planRound + 1;
-    return { action: 'plan-task', role: 'executor', stage: 'plan', round, artifact: artifactName('plan', round) };
-  }
-  if (!hasReviewAfterArtifact(taskDir, 'plan', 'review-plan')) {
-    const round = planReviewRound + 1;
-    return { action: 'review-plan', role: 'reviewer', stage: 'review-plan', round, artifact: artifactName('review-plan', round) };
-  }
-  const planVerdict = latestReviewApproved(taskDir, 'review-plan');
-  if (planVerdict.error) return { error: planVerdict.error };
-  if (!planVerdict.approved) {
-    const round = planRound + 1;
-    return { action: 'plan-task', role: 'executor', stage: 'plan', round, artifact: artifactName('plan', round) };
-  }
-  if (codeRound === 0) {
-    const round = codeRound + 1;
-    return { action: 'code-task', role: 'executor', stage: 'code', round, artifact: artifactName('code', round) };
-  }
-  if (!hasReviewAfterArtifact(taskDir, 'code', 'review-code')) {
-    const round = codeReviewRound + 1;
-    return { action: 'review-code', role: 'reviewer', stage: 'review-code', round, artifact: artifactName('review-code', round) };
-  }
-  const codeVerdict = latestReviewApproved(taskDir, 'review-code');
-  if (codeVerdict.error) return { error: codeVerdict.error };
-  if (!codeVerdict.approved) {
-    const round = codeRound + 1;
-    return { action: 'code-task', role: 'executor', stage: 'code', round, artifact: artifactName('code', round) };
-  }
-  return { action: 'commit', role: 'executor', stage: 'commit', round: 1, artifact: 'commit' };
+function routeFromFacts(facts: LifecycleFacts): Omit<OrchestrationNext, 'requestedModel' | 'requestedReasoningEffort'> | { completion: true } | null {
+  const recommendation = recommendNext(facts);
+  if (!recommendation.action) return { completion: true };
+  const action = recommendation.action;
+  if (action === 'manual-validation' || action === 'validation-run') return null;
+  const family = action === 'analysis' ? 'analysis' : action;
+  const round = Math.max(0, ...[...(facts.artifacts[family] ?? []), ...(facts.staleArtifacts?.[family] ?? [])].map((name) => {
+    const match = /-r(\d+)\.md$/.exec(name);
+    return match ? Number(match[1]) : 1;
+  })) + 1;
+  const command = action === 'analysis' ? 'analyze-task' : action === 'plan' ? 'plan-task' : action === 'code' ? 'code-task' : action;
+  const role = action.startsWith('review-') ? 'reviewer' : 'executor';
+  return { action: command, role, stage: action, round, artifact: artifactName(family, round) };
 }
 
 function routeOrchestration(taskRef: string, options: OrchestrationOptions = {}): OrchestrationResult {
@@ -652,11 +597,13 @@ 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);
@@ -664,17 +611,25 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
       return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
   }
-  const routed = routeFromFacts(resolved.taskDir);
-  if (routed && 'error' in routed) return failed('ORCHESTRATION_REVIEW_INVALID', routed.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);
+  } catch (error) {
+    return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
+  const facts = buildLifecycleFacts(
+    resolved.taskDir,
+    content,
+    resolved.state,
+    hasOpenLifecycleExecution(content) || Boolean(run?.pendingDelegation)
+  );
+  if (!facts.ok) return failed('ORCHESTRATION_CAPABILITY_FACTS_INVALID', facts.message, resolved.taskId);
+  const routed = routeFromFacts(facts.facts);
   if (!routed) return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
-  const run = readRun(resolved.taskDir);
-  const policy = run ? rolePolicy(run, routed.role) : null;
-  const next: OrchestrationNext = {
-    ...routed,
-    requestedModel: policy?.model ?? null,
-    requestedReasoningEffort: policy?.reasoningEffort ?? null
-  };
-  if (next.stage === 'commit') {
+  if ('completion' in routed) {
     const reviewRound = highestRound(resolved.taskDir, 'review-code');
     const review = parseReviewSummary(fs.readFileSync(
       path.join(resolved.taskDir, artifactName('review-code', reviewRound)),
@@ -756,6 +711,18 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     saveRun(resolved.taskDir, completed);
     return { status: 'completed', changed: true, taskId: resolved.taskId, run: completed, next: null, error: null };
   }
+  const action = routed.stage as LifecycleAction;
+  const capability = canStart(action, facts.facts, {
+    initiator: 'orchestrator', requestId: `orchestration:${resolved.taskId}:${routed.stage}:${routed.round}`,
+    requestedAction: action, reasonCode: 'user-request', explicitRequest: true
+  });
+  if (!capability.allowed) return failed('ORCHESTRATION_CAPABILITY_DENIED', `${capability.reasonCode}: ${capability.evidence.join(', ')}`, resolved.taskId);
+  const policy = run ? rolePolicy(run, routed.role) : null;
+  const next: OrchestrationNext = {
+    ...routed,
+    requestedModel: policy?.model ?? null,
+    requestedReasoningEffort: policy?.reasoningEffort ?? null
+  };
   return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
 }
 

package/lib/task/pr-delivery-fact.ts

@@ -1,6 +1,23 @@
+import type { ResourceIdentity } from '../platform/resource-identity.ts';
+import { isLegacyCompatibilityEnabled, legacyCompatibilityError, VERSION } from '../version.ts';
+import {
+  isResourceIdentity,
+  parseResourceIdentity,
+  resourceIdentityNumber,
+  serializeResourceIdentity
+} from '../platform/resource-identity.ts';
+
 const PR_DELIVERY_FACT_KEY = 'pr_delivery_fact';
 
 type PrDeliveryIdentity = {
+  resource: ResourceIdentity;
+  repository: string;
+  url: string;
+  head: { repository: string; ref: string; sha: string };
+  base: { repository: string; ref: string; sha: string };
+};
+
+type LegacyPrDeliveryIdentity = {
   repository: string;
   number: number;
   nodeId: string;
@@ -8,33 +25,30 @@ type PrDeliveryIdentity = {
   head: { repository: string; ref: string; sha: string };
   base: { repository: string; ref: string; sha: string };
 };
+type CurrentPrDeliveryIdentityInput = {
+  resource: ResourceIdentity;
+  repository: string;
+  url: string;
+  head: { repository: string; ref: string; sha: string };
+  base: { repository: string; ref: string; sha: string };
+};
+type PrDeliveryIdentityInput = CurrentPrDeliveryIdentityInput;
 
-type PrDeliveryBindingSource =
-  | 'created'
-  | 'reused'
-  | 'explicit-bind'
-  | 'external-unique'
-  | 'external-explicit';
-
-type PrDeliveryProvenance =
-  | 'create-post'
-  | 'reuse'
-  | 'explicit-bind'
-  | 'external-unique'
-  | 'external-explicit';
+type PrDeliveryBindingSource = 'created' | 'reused' | 'explicit-bind' | 'external-unique' | 'external-explicit';
+type PrDeliveryProvenance = 'create-post' | 'reuse' | 'explicit-bind' | 'external-unique' | 'external-explicit';
 
 type PrDeliveryFact =
-  | { version: 1; state: 'unbound'; reason: 'initial' }
-  | { version: 1; state: 'skipped'; reason: 'explicit'; decidedAt: string }
+  | { version: 2; state: 'unbound'; reason: 'initial' }
+  | { version: 2; state: 'skipped'; reason: 'explicit'; decidedAt: string }
   | {
-      version: 1;
+      version: 2;
       state: 'bound';
       identity: PrDeliveryIdentity;
       binding: {
         status: 'verified';
         source: PrDeliveryBindingSource;
         verifiedAt: string;
-        issueNumber: number | null;
+        issueIdentity: ResourceIdentity | null;
         remoteState: 'open' | 'closed';
         mergedAt: string | null;
         mergeCommitSha: string | null;
@@ -50,205 +64,174 @@ type CreationOutcome =
   | { kind: 'no-op'; createdByCurrentOperation: false }
   | { kind: 'unknown'; errorCode: 'PR_CREATE_OUTCOME_UNKNOWN' };
 
+type PrDeliveryFactError = Error & { code: string };
 type PrDeliveryFactReadResult =
   | { status: 'valid'; fact: PrDeliveryFact }
   | { status: 'missing'; fact: null }
-  | { status: 'invalid'; fact: null; error: Error };
+  | { status: 'invalid'; fact: null; error: PrDeliveryFactError };
 
 function factError(message: string): Error & { code: string } {
   return Object.assign(new Error(`PR_DELIVERY_FACT_INVALID: ${message}`), { code: 'PR_DELIVERY_FACT_INVALID' });
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+function asFactError(error: unknown): PrDeliveryFactError {
+  if (error instanceof Error && typeof (error as { code?: unknown }).code === 'string') return error as PrDeliveryFactError;
+  return factError(error instanceof Error ? error.message : String(error));
 }
-
+function isRecord(value: unknown): value is Record<string, unknown> { return Boolean(value) && typeof value === 'object' && !Array.isArray(value); }
 function exactKeys(value: Record<string, unknown>, keys: readonly string[], label: string): void {
   const actual = Object.keys(value).sort();
   const expected = [...keys].sort();
-  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
-    throw factError(`${label} has an invalid field set`);
-  }
+  if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) throw factError(`${label} has an invalid field set`);
 }
-
-function text(value: unknown, label: string): string {
-  if (typeof value !== 'string' || !value || value.trim() !== value) throw factError(`${label} must be a non-empty string`);
+function text(value: unknown, label: string, allowEmpty = false): string {
+  if (typeof value !== 'string' || (!allowEmpty && !value) || value.trim() !== value) throw factError(`${label} must be a string`);
   return value;
 }
-
-function nullableText(value: unknown, label: string): string | null {
-  return value === null ? null : text(value, label);
+function nullableText(value: unknown, label: string): string | null { return value === null ? null : text(value, label); }
+function timestamp(value: unknown, label: string): string {
+  const result = text(value, label);
+  if (Number.isNaN(Date.parse(result))) throw factError(`${label} must be a valid timestamp`);
+  return new Date(result).toISOString();
 }
-
 function positiveNumber(value: unknown, label: string): number {
   if (!Number.isSafeInteger(value) || (value as number) <= 0) throw factError(`${label} must be a positive integer`);
   return value as number;
 }
-
-function optionalTimestamp(value: unknown, label: string): string | null {
-  const result = nullableText(value, label);
-  if (result !== null && Number.isNaN(Date.parse(result))) throw factError(`${label} must be a valid timestamp`);
-  return result;
+function parseRef(value: unknown, label: string): { repository: string; ref: string; sha: string } {
+  if (!isRecord(value)) throw factError(`${label} must be an object`);
+  exactKeys(value, ['repository', 'ref', 'sha'], label);
+  return { repository: text(value.repository, `${label}.repository`), ref: text(value.ref, `${label}.ref`), sha: text(value.sha, `${label}.sha`) };
 }
 
-function parseIdentity(value: unknown): PrDeliveryIdentity {
+function canonicalIdentity(value: unknown): PrDeliveryIdentity {
   if (!isRecord(value)) throw factError('identity must be an object');
-  exactKeys(value, ['repository', 'number', 'nodeId', 'url', 'head', 'base'], 'identity');
-  const head = parseRef(value.head, 'head');
-  const base = parseRef(value.base, 'base');
+  exactKeys(value, ['resource', 'repository', 'url', 'head', 'base'], 'identity');
   return {
+    resource: parseResourceIdentity(value.resource, 'identity.resource'),
     repository: text(value.repository, 'identity.repository'),
-    number: positiveNumber(value.number, 'identity.number'),
-    nodeId: text(value.nodeId, 'identity.nodeId'),
     url: text(value.url, 'identity.url'),
-    head,
-    base
+    head: parseRef(value.head, 'identity.head'),
+    base: parseRef(value.base, 'identity.base')
   };
 }
 
-function parseRef(value: unknown, label: string): { repository: string; ref: string; sha: string } {
-  if (!isRecord(value)) throw factError(`${label} must be an object`);
-  exactKeys(value, ['repository', 'ref', 'sha'], label);
+function decodeLegacyIdentity(value: unknown): PrDeliveryIdentity {
+  if (!isRecord(value)) throw factError('legacy identity must be an object');
+  // TODO(compat): Remove the v1 identity decoder before the first stable v1.0.0 release.
+  exactKeys(value, ['repository', 'number', 'nodeId', 'url', 'head', 'base'], 'legacy identity');
+  const legacy = {
+    number: positiveNumber(value.number, 'legacy identity.number'),
+    repository: text(value.repository, 'identity.repository'),
+    nodeId: text(value.nodeId, 'legacy identity.nodeId'),
+    url: text(value.url, 'identity.url'),
+    head: parseRef(value.head, 'identity.head'),
+    base: parseRef(value.base, 'identity.base')
+  } satisfies LegacyPrDeliveryIdentity;
   return {
-    repository: text(value.repository, `${label}.repository`),
-    ref: text(value.ref, `${label}.ref`),
-    sha: text(value.sha, `${label}.sha`)
+    resource: { kind: 'number', value: legacy.number },
+    repository: legacy.repository,
+    url: legacy.url,
+    head: legacy.head,
+    base: legacy.base
   };
 }
 
-function parseFact(value: unknown): PrDeliveryFact {
+function provenanceForSource(source: PrDeliveryBindingSource): PrDeliveryProvenance { return source === 'created' ? 'create-post' : source === 'reused' ? 'reuse' : source; }
+
+function parseFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
   if (!isRecord(value)) throw factError('fact must be an object');
-  if (value.version !== 1 || typeof value.state !== 'string') throw factError('version or state is invalid');
+  if ((value.version !== 1 && value.version !== 2) || typeof value.state !== 'string') throw factError('version or state is invalid');
+  if (value.version === 1 && !isLegacyCompatibilityEnabled(runtimeVersion)) {
+    throw legacyCompatibilityError('v1 PR delivery fact', runtimeVersion);
+  }
   if (value.state === 'unbound') {
     exactKeys(value, ['version', 'state', 'reason'], 'unbound fact');
     if (value.reason !== 'initial') throw factError('unbound reason is invalid');
-    return { version: 1, state: 'unbound', reason: value.reason };
+    return { version: 2, state: 'unbound', reason: 'initial' };
   }
   if (value.state === 'skipped') {
     exactKeys(value, ['version', 'state', 'reason', 'decidedAt'], 'skipped fact');
     if (value.reason !== 'explicit') throw factError('skipped reason is invalid');
-    const decidedAt = text(value.decidedAt, 'skipped.decidedAt');
-    if (Number.isNaN(Date.parse(decidedAt))) throw factError('skipped.decidedAt must be a valid timestamp');
-    return { version: 1, state: 'skipped', reason: 'explicit', decidedAt };
+    return { version: 2, state: 'skipped', reason: 'explicit', decidedAt: timestamp(value.decidedAt, 'skipped.decidedAt') };
   }
   if (value.state !== 'bound') throw factError('state is invalid');
+  if (value.version === 1) {
+    // TODO(compat): Remove this v1-to-v2 shape conversion before the first stable v1.0.0 release.
+    exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'legacy bound fact');
+    if (!isRecord(value.binding) || !isRecord(value.provenance)) throw factError('legacy binding or provenance is invalid');
+    exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueNumber', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'legacy binding');
+    const issueNumber = value.binding.issueNumber === null ? null : positiveNumber(value.binding.issueNumber, 'legacy binding.issueNumber');
+    return parseFact({
+      version: 2,
+      state: 'bound',
+      identity: decodeLegacyIdentity(value.identity),
+      binding: {
+        status: 'verified', source: value.binding.source, verifiedAt: timestamp(value.binding.verifiedAt, 'binding.verifiedAt'),
+        issueIdentity: issueNumber === null ? null : { kind: 'number', value: issueNumber }, remoteState: value.binding.remoteState,
+        mergedAt: value.binding.mergedAt === null ? null : timestamp(value.binding.mergedAt, 'binding.mergedAt'), mergeCommitSha: nullableText(value.binding.mergeCommitSha, 'binding.mergeCommitSha')
+      },
+      provenance: value.provenance
+    }, runtimeVersion);
+  }
   exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'bound fact');
-  if (!isRecord(value.binding)) throw factError('binding must be an object');
-  exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueNumber', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'binding');
+  if (!isRecord(value.binding) || !isRecord(value.provenance)) throw factError('binding or provenance is invalid');
+  exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueIdentity', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'binding');
   if (value.binding.status !== 'verified') throw factError('binding status is invalid');
   const sources: readonly PrDeliveryBindingSource[] = ['created', 'reused', 'explicit-bind', 'external-unique', 'external-explicit'];
   if (!sources.includes(value.binding.source as PrDeliveryBindingSource)) throw factError('binding source is invalid');
-  const verifiedAt = text(value.binding.verifiedAt, 'binding.verifiedAt');
-  if (Number.isNaN(Date.parse(verifiedAt))) throw factError('binding.verifiedAt must be a valid timestamp');
-  const issueNumber = value.binding.issueNumber === null ? null : positiveNumber(value.binding.issueNumber, 'binding.issueNumber');
+  const issueIdentity = value.binding.issueIdentity === null ? null : parseResourceIdentity(value.binding.issueIdentity, 'binding.issueIdentity');
   if (value.binding.remoteState !== 'open' && value.binding.remoteState !== 'closed') throw factError('binding.remoteState is invalid');
-  const mergedAt = optionalTimestamp(value.binding.mergedAt, 'binding.mergedAt');
+  const mergedAt = value.binding.mergedAt === null ? null : timestamp(value.binding.mergedAt, 'binding.mergedAt');
   const mergeCommitSha = nullableText(value.binding.mergeCommitSha, 'binding.mergeCommitSha');
   if (Boolean(mergedAt) !== Boolean(mergeCommitSha)) throw factError('mergedAt and mergeCommitSha must be paired');
-  if (!isRecord(value.provenance)) throw factError('provenance must be an object');
   exactKeys(value.provenance, ['establishedBy'], 'provenance');
-  const provenance: readonly PrDeliveryProvenance[] = ['create-post', 'reuse', 'explicit-bind', 'external-unique', 'external-explicit'];
-  if (!provenance.includes(value.provenance.establishedBy as PrDeliveryProvenance)) throw factError('provenance.establishedBy is invalid');
-  if (value.provenance.establishedBy !== provenanceForSource(value.binding.source as PrDeliveryBindingSource)) {
-    throw factError('binding.source and provenance.establishedBy do not match');
-  }
+  const provenances: readonly PrDeliveryProvenance[] = ['create-post', 'reuse', 'explicit-bind', 'external-unique', 'external-explicit'];
+  if (!provenances.includes(value.provenance.establishedBy as PrDeliveryProvenance)) throw factError('provenance.establishedBy is invalid');
+  if (value.provenance.establishedBy !== provenanceForSource(value.binding.source as PrDeliveryBindingSource)) throw factError('binding.source and provenance.establishedBy do not match');
   return {
-    version: 1,
-    state: 'bound',
-    identity: parseIdentity(value.identity),
-    binding: {
-      status: 'verified',
-      source: value.binding.source as PrDeliveryBindingSource,
-      verifiedAt,
-      issueNumber,
-      remoteState: value.binding.remoteState,
-      mergedAt,
-      mergeCommitSha
-    },
+    version: 2, state: 'bound', identity: canonicalIdentity(value.identity),
+    binding: { status: 'verified', source: value.binding.source as PrDeliveryBindingSource, verifiedAt: timestamp(value.binding.verifiedAt, 'binding.verifiedAt'), issueIdentity, remoteState: value.binding.remoteState, mergedAt, mergeCommitSha },
     provenance: { establishedBy: value.provenance.establishedBy as PrDeliveryProvenance }
   };
 }
 
-function decodePrDeliveryFact(value: unknown): PrDeliveryFact {
+function decodePrDeliveryFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
   if (typeof value === 'string') {
-    try { return parseFact(JSON.parse(value)); }
-    catch (error) { throw error instanceof Error && error.message.startsWith('PR_DELIVERY_FACT_INVALID:') ? error : factError('value is not valid JSON'); }
+    let decoded: unknown;
+    try { decoded = JSON.parse(value); }
+    catch { throw factError('value is not valid JSON'); }
+    return parseFact(decoded, runtimeVersion);
   }
-  return parseFact(value);
+  return parseFact(value, runtimeVersion);
 }
-
-function encodePrDeliveryFact(fact: PrDeliveryFact): string {
-  return JSON.stringify(parseFact(fact));
-}
-
-function readPrDeliveryFact(metadata: Record<string, unknown>): PrDeliveryFactReadResult {
+function encodePrDeliveryFact(fact: PrDeliveryFact): string { return JSON.stringify(parseFact(fact)); }
+function readPrDeliveryFact(metadata: Record<string, unknown>, runtimeVersion = VERSION): PrDeliveryFactReadResult {
   if (!Object.hasOwn(metadata, PR_DELIVERY_FACT_KEY) || metadata[PR_DELIVERY_FACT_KEY] === '') return { status: 'missing', fact: null };
-  try { return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY]) }; }
-  catch (error) { return { status: 'invalid', fact: null, error: error instanceof Error ? error : factError(String(error)) }; }
-}
-
-function buildUnboundFact(): PrDeliveryFact {
-  return { version: 1, state: 'unbound', reason: 'initial' };
-}
-
-function buildSkippedFact(decidedAt: string): PrDeliveryFact {
-  return parseFact({ version: 1, state: 'skipped', reason: 'explicit', decidedAt });
-}
-
-function provenanceForSource(source: PrDeliveryBindingSource): PrDeliveryProvenance {
-  return source === 'created' ? 'create-post' : source === 'reused' ? 'reuse' : source;
+  try { return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY], runtimeVersion) }; }
+  catch (error) { return { status: 'invalid', fact: null, error: asFactError(error) }; }
 }
+function buildUnboundFact(): PrDeliveryFact { return { version: 2, state: 'unbound', reason: 'initial' }; }
+function buildSkippedFact(decidedAt: string): PrDeliveryFact { return parseFact({ version: 2, state: 'skipped', reason: 'explicit', decidedAt }); }
 
 function buildBoundFact(input: {
-  identity: PrDeliveryIdentity;
+  identity: CurrentPrDeliveryIdentityInput;
   source: PrDeliveryBindingSource;
   verifiedAt: string;
-  issueNumber?: number | null;
+  issueIdentity?: ResourceIdentity | null;
   remoteState: 'open' | 'closed';
   mergedAt?: string | null;
   mergeCommitSha?: string | null;
 }): PrDeliveryFact {
-  return parseFact({
-    version: 1,
-    state: 'bound',
-    identity: input.identity,
-    binding: {
-      status: 'verified',
-      source: input.source,
-      verifiedAt: input.verifiedAt,
-      issueNumber: input.issueNumber ?? null,
-      remoteState: input.remoteState,
-      mergedAt: input.mergedAt ?? null,
-      mergeCommitSha: input.mergeCommitSha ?? null
-    },
-    provenance: { establishedBy: provenanceForSource(input.source) }
-  });
+  return parseFact({ version: 2, state: 'bound', identity: input.identity, binding: {
+    status: 'verified', source: input.source, verifiedAt: input.verifiedAt,
+    issueIdentity: input.issueIdentity === undefined ? null : input.issueIdentity,
+    remoteState: input.remoteState, mergedAt: input.mergedAt ?? null, mergeCommitSha: input.mergeCommitSha ?? null
+  }, provenance: { establishedBy: provenanceForSource(input.source) } });
 }
-
-function factFrontmatterMutation(fact: PrDeliveryFact): { set: { [PR_DELIVERY_FACT_KEY]: string } } {
-  return { set: { [PR_DELIVERY_FACT_KEY]: encodePrDeliveryFact(fact) } };
-}
-
-function identityFromPullRequest(pullRequest: PrDeliveryIdentity): PrDeliveryIdentity {
-  return parseIdentity(pullRequest);
+function factFrontmatterMutation(fact: PrDeliveryFact): { set: { [PR_DELIVERY_FACT_KEY]: string } } { return { set: { [PR_DELIVERY_FACT_KEY]: encodePrDeliveryFact(fact) } }; }
+function identityFromPullRequest(pullRequest: PrDeliveryIdentityInput): PrDeliveryIdentity {
+  return canonicalIdentity(pullRequest);
 }
 
-export {
-  PR_DELIVERY_FACT_KEY,
-  buildBoundFact,
-  buildSkippedFact,
-  buildUnboundFact,
-  decodePrDeliveryFact,
-  encodePrDeliveryFact,
-  factFrontmatterMutation,
-  identityFromPullRequest,
-  readPrDeliveryFact
-};
-export type {
-  CreationOutcome,
-  PrDeliveryBindingSource,
-  PrDeliveryFact,
-  PrDeliveryFactReadResult,
-  PrDeliveryIdentity,
-  PrDeliveryProvenance
-};
+export { PR_DELIVERY_FACT_KEY, buildBoundFact, buildSkippedFact, buildUnboundFact, decodePrDeliveryFact, encodePrDeliveryFact, factFrontmatterMutation, identityFromPullRequest, readPrDeliveryFact, serializeResourceIdentity };
+export type { CreationOutcome, PrDeliveryBindingSource, PrDeliveryFact, PrDeliveryFactError, PrDeliveryFactReadResult, PrDeliveryIdentity, PrDeliveryIdentityInput, PrDeliveryProvenance };

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
   };
 }