@fitlab-ai/agent-infra 0.9.11 → 0.9.13

package/dist/lib/task/orchestration.js

@@ -3,20 +3,23 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { parseTypedTaskFrontmatter } from './frontmatter.js';
 import { validateCurrentTaskContract } from './current-contract.js';
-import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.js';
-import { inspectArtifactDirectory } from './artifact-lifecycle.js';
+import { parseReviewSummary } from './review-artifacts.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { activateDelegation, abortPreparedDelegation, completeDelegationStage, consumeDelegation, dispatchDelegation, foldBlankToNull, isDelegationReceipt, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
 import { normalizeAgentClients } from '../agent-clients/config.js';
 import { resolveAgentRuntimeStoreRoot } from '../runtime/agent-runtime.js';
-import { inspectPlatformPullRequest } from '../platform/pull-requests.js';
 import { getAgentClientCapability, getAgentClientDelegationEvidence, getAgentClientModelSelection } from '../agent-clients/registry.js';
 import { isAgentClientId } from '../agent-clients/types.js';
 import { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots } from './workspace-snapshot.js';
 import { assertGitRepositoryBinding } from '../git/worktree-identity.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 import { hasActiveCodexLifecycleEvidence } from '../agent-clients/adapters/codex-lifecycle/store.js';
+import { extractReviewBaseline, extractReviewDiffBase, extractReviewTargetHead, extractReviewedHead } from './review-fingerprint.js';
+import { resolveDeliveryTarget, resolveDiffBase, resolveTargetHead } from './delivery-target.js';
+import { buildLifecycleFacts, canStart, recommendNext } from './capabilities.js';
+import { hasOpenLifecycleExecution } from './activity-log.js';
+import { invalidationBlocks } from './invalidation.js';
 function supportsLifecycleDelegation(client) {
     return getAgentClientCapability(client, 'subagents').level !== 'unsupported'
         && getAgentClientCapability(client, 'orchestration').level !== 'unsupported'
@@ -106,9 +109,8 @@ function isCompletionEvidence(value) {
         && exactText(value.headTree)
         && exactText(value.worktreeTree)
         && exactText(value.lastReviewedCommit)
-        && Number.isSafeInteger(value.prNumber)
-        && value.prNumber > 0
-        && exactText(value.prHead);
+        && (value.prNumber === null || (Number.isSafeInteger(value.prNumber) && value.prNumber > 0))
+        && (value.prHead === null || exactText(value.prHead));
 }
 const ORCHESTRATION_RUN_KEYS = [
     'taskId', 'runId', 'status', 'nextStage', 'stepCount', 'maxSteps', 'modelPolicy',
@@ -340,86 +342,58 @@ function highestRound(taskDir, family) {
 function artifactName(family, round) {
     return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
 }
-function hasReviewAfterArtifact(taskDir, family, reviewFamily) {
-    const artifact = inspectArtifactDirectory(taskDir, family);
-    const review = inspectArtifactDirectory(taskDir, reviewFamily);
-    return artifact.status === 'ready'
-        && review.status === 'ready'
-        && artifact.latest !== null
-        && review.reviewedInput?.name === artifact.latest.name;
-}
-function latestReviewApproved(taskDir, family) {
-    const round = highestRound(taskDir, family);
-    if (round === 0)
-        return { approved: false, error: null };
-    let content;
-    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) {
-    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) };
+function validateSavedCurrentDiffBase(repoRoot, metadata, taskDir, reviewedHead) {
+    const reviewRound = highestRound(taskDir, 'review-code');
+    const reviewContent = fs.readFileSync(path.join(taskDir, artifactName('review-code', reviewRound)), 'utf8');
+    const savedTargetHead = extractReviewTargetHead(reviewContent);
+    const savedDiffBase = extractReviewDiffBase(reviewContent);
+    const savedReviewedHead = extractReviewedHead(reviewContent) || extractReviewBaseline(reviewContent);
+    if (!savedTargetHead && !savedDiffBase && !savedReviewedHead)
+        return null;
+    if (savedReviewedHead && savedReviewedHead !== reviewedHead) {
+        return { code: 'ORCHESTRATION_REVIEWED_HEAD_MISMATCH', message: 'review-code saved reviewed head does not match last_reviewed_commit' };
     }
-    if (codeRound === 0) {
-        const round = codeRound + 1;
-        return { action: 'code-task', role: 'executor', stage: 'code', round, artifact: artifactName('code', round) };
+    if (!savedTargetHead || !savedDiffBase) {
+        return { code: 'ORCHESTRATION_REVIEW_TARGET_INVALID', message: 'review-code must save target head and diff base together' };
     }
-    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 savedBase = resolveDiffBase(repoRoot, reviewedHead, savedTargetHead);
+    if (!savedBase.ok)
+        return { code: 'ORCHESTRATION_REVIEW_TARGET_INVALID', message: savedBase.message };
+    if (savedBase.diffBase !== savedDiffBase) {
+        return { code: 'ORCHESTRATION_REVIEW_DIFF_BASE_MISMATCH', message: 'saved review diff base does not match reviewed head and saved target head' };
     }
-    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) };
+    const target = resolveDeliveryTarget(repoRoot, {
+        remote: typeof metadata.delivery_remote === 'string' ? metadata.delivery_remote : undefined,
+        baseRef: typeof metadata.delivery_base_ref === 'string' ? metadata.delivery_base_ref : undefined
+    });
+    if (!target.ok)
+        return { code: target.code, message: target.message };
+    const currentTarget = resolveTargetHead(repoRoot, target.value);
+    if (!currentTarget.ok)
+        return { code: currentTarget.code, message: currentTarget.message };
+    const currentBase = resolveDiffBase(repoRoot, reviewedHead, currentTarget.head);
+    if (!currentBase.ok)
+        return { code: currentBase.code, message: currentBase.message };
+    if (currentBase.diffBase !== savedDiffBase) {
+        return { code: 'ORCHESTRATION_REVIEW_TARGET_CHANGED', message: 'current delivery target changed the reviewed diff base; re-run review-code' };
     }
-    return { action: 'commit', role: 'executor', stage: 'commit', round: 1, artifact: 'commit' };
+    return null;
+}
+function routeFromFacts(facts) {
+    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, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
@@ -441,12 +415,14 @@ function routeOrchestration(taskRef, options = {}) {
     }
     let metadata;
     let currentLedger = null;
+    let currentInvalidation = { 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 {
@@ -456,19 +432,23 @@ function routeOrchestration(taskRef, options = {}) {
             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;
+    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 = {
-        ...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)), 'utf8'));
         if (!review.ok || review.summary.manualValidation === null) {
@@ -487,29 +467,8 @@ function routeOrchestration(taskRef, options = {}) {
         if (run?.status === 'completed') {
             return { status: 'completed', changed: false, taskId: resolved.taskId, run, next: null, error: null };
         }
-        let config;
-        try {
-            config = JSON.parse(fs.readFileSync(path.join(resolved.repoRoot, '.agents', '.airc.json'), 'utf8'));
-        }
-        catch (error) {
-            return failed('ORCHESTRATION_CONFIG_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
-        }
-        if (!config || typeof config !== 'object' || Array.isArray(config)) {
-            return failed('ORCHESTRATION_CONFIG_INVALID', 'project configuration must be an object', resolved.taskId);
-        }
-        const projectConfig = config;
-        if (!Object.hasOwn(projectConfig, 'prFlow') || projectConfig.prFlow === 'disabled') {
-            return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
-        }
-        if (projectConfig.prFlow !== 'required') {
-            return failed('ORCHESTRATION_CONFIG_INVALID', "project configuration 'prFlow' must be 'required' or 'disabled'", resolved.taskId);
-        }
-        const prNumber = Number(metadata.pr_number);
-        if (!Number.isInteger(prNumber) || prNumber <= 0) {
-            return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
-        }
         if (!run) {
-            return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+            return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
         }
         if (run.status !== 'running' || run.pendingDelegation !== null) {
             return failed('ORCHESTRATION_RUN_NOT_RUNNING', 'clean completion requires an idle running orchestration', resolved.taskId);
@@ -523,34 +482,15 @@ function routeOrchestration(taskRef, options = {}) {
             return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
         }
         if (before.headTree !== before.worktreeTree) {
-            return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+            return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
         }
         const lastReviewedCommit = String(metadata.last_reviewed_commit ?? '');
         if (before.head !== lastReviewedCommit) {
             return failed('ORCHESTRATION_REVIEWED_HEAD_MISMATCH', 'local HEAD does not match last_reviewed_commit', resolved.taskId);
         }
-        const inspect = options.inspectPullRequest ?? inspectPlatformPullRequest;
-        let inspection;
-        try {
-            inspection = inspect(resolved.taskId, { cwd: gitRoot });
-        }
-        catch (error) {
-            return failed('ORCHESTRATION_PR_INSPECTION_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
-        }
-        if (inspection.status === 'blocked') {
-            return failed('ORCHESTRATION_PR_INSPECTION_BLOCKED', inspection.error?.message ?? 'pull request inspection is blocked', resolved.taskId);
-        }
-        if (inspection.status === 'failed') {
-            return failed('ORCHESTRATION_PR_INSPECTION_FAILED', inspection.error?.message ?? 'pull request inspection failed', resolved.taskId);
-        }
-        const inspectedPrNumber = inspection.task?.prNumber ?? inspection.prNumber;
-        const prHead = inspection.pullRequest?.head?.sha;
-        if (typeof prHead !== 'string') {
-            return failed('ORCHESTRATION_PR_INSPECTION_INVALID', 'pull request inspection returned incomplete identity evidence', resolved.taskId);
-        }
-        if (inspectedPrNumber !== prNumber || prHead !== before.head) {
-            return failed('ORCHESTRATION_PR_HEAD_MISMATCH', 'pull request identity does not match the reviewed local HEAD', resolved.taskId);
-        }
+        const diffBaseError = validateSavedCurrentDiffBase(resolved.repoRoot, metadata, resolved.taskDir, lastReviewedCommit);
+        if (diffBaseError)
+            return failed(diffBaseError.code, diffBaseError.message, resolved.taskId);
         let after;
         try {
             after = capture(gitRoot);
@@ -559,7 +499,7 @@ function routeOrchestration(taskRef, options = {}) {
             return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
         }
         if (after.headTree !== after.worktreeTree) {
-            return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+            return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
         }
         if (after.head !== before.head || after.headTree !== before.headTree) {
             return failed('ORCHESTRATION_REPOSITORY_CHANGED', 'repository changed while clean completion evidence was collected', resolved.taskId);
@@ -572,8 +512,8 @@ function routeOrchestration(taskRef, options = {}) {
             headTree: after.headTree,
             worktreeTree: after.worktreeTree,
             lastReviewedCommit,
-            prNumber,
-            prHead
+            prNumber: null,
+            prHead: null
         };
         const completed = withUpdatedRun(run, {
             status: 'completed',
@@ -584,6 +524,19 @@ function routeOrchestration(taskRef, options = {}) {
         saveRun(resolved.taskDir, completed);
         return { status: 'completed', changed: true, taskId: resolved.taskId, run: completed, next: null, error: null };
     }
+    const action = routed.stage;
+    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 = {
+        ...routed,
+        requestedModel: policy?.model ?? null,
+        requestedReasoningEffort: policy?.reasoningEffort ?? null
+    };
     return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
 }
 function statusOrchestration(taskRef, options = {}) {
@@ -668,10 +621,7 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
     }
     const updated = withUpdatedRun(run, {
         nextStage: next.stage,
-        pendingDelegation: receipt,
-        commitAuthorization: next.stage === 'commit' && run.commitAuthorization.issuedAt === null
-            ? { issuedAt: (options.now ?? (() => new Date().toISOString()))(), consumedAt: null }
-            : run.commitAuthorization
+        pendingDelegation: receipt
     });
     saveRun(resolved.taskDir, updated);
     return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next, error: null };
@@ -1093,16 +1043,15 @@ function advanceOrchestration(taskRef, options = {}) {
     const result = consumeDelegation(run.pendingDelegation, { now: options.now });
     if (!result.ok)
         return pauseOrchestration(taskRef, result.code, result.message, true, options);
-    const completed = result.receipt.stage === 'commit';
+    if (result.receipt.stage === 'commit') {
+        return failed('ORCHESTRATED_COMMIT_REMOVED', 'Orchestrated commit is no longer a lifecycle stage; use local checkpoint delivery from code-task', resolved.taskId);
+    }
     const updated = withUpdatedRun(run, {
-        status: completed ? 'completed' : 'running',
+        status: 'running',
         nextStage: null,
         stepCount: run.stepCount + 1,
         pendingDelegation: null,
-        receipts: Object.freeze([...run.receipts, result.receipt]),
-        commitAuthorization: completed
-            ? { ...run.commitAuthorization, consumedAt: (options.now ?? (() => new Date().toISOString()))() }
-            : run.commitAuthorization
+        receipts: Object.freeze([...run.receipts, result.receipt])
     });
     saveRun(resolved.taskDir, updated);
     return { status: updated.status, changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };

package/dist/lib/task/pr-delivery-fact.js

@@ -0,0 +1,183 @@
+import { isLegacyCompatibilityEnabled, legacyCompatibilityError, VERSION } from '../version.js';
+import { isResourceIdentity, parseResourceIdentity, resourceIdentityNumber, serializeResourceIdentity } from '../platform/resource-identity.js';
+const PR_DELIVERY_FACT_KEY = 'pr_delivery_fact';
+function factError(message) {
+    return Object.assign(new Error(`PR_DELIVERY_FACT_INVALID: ${message}`), { code: 'PR_DELIVERY_FACT_INVALID' });
+}
+function asFactError(error) {
+    if (error instanceof Error && typeof error.code === 'string')
+        return error;
+    return factError(error instanceof Error ? error.message : String(error));
+}
+function isRecord(value) { return Boolean(value) && typeof value === 'object' && !Array.isArray(value); }
+function exactKeys(value, keys, label) {
+    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`);
+}
+function text(value, label, allowEmpty = false) {
+    if (typeof value !== 'string' || (!allowEmpty && !value) || value.trim() !== value)
+        throw factError(`${label} must be a string`);
+    return value;
+}
+function nullableText(value, label) { return value === null ? null : text(value, label); }
+function timestamp(value, label) {
+    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, label) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw factError(`${label} must be a positive integer`);
+    return value;
+}
+function parseRef(value, label) {
+    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 canonicalIdentity(value) {
+    if (!isRecord(value))
+        throw factError('identity must be an object');
+    exactKeys(value, ['resource', 'repository', 'url', 'head', 'base'], 'identity');
+    return {
+        resource: parseResourceIdentity(value.resource, 'identity.resource'),
+        repository: text(value.repository, 'identity.repository'),
+        url: text(value.url, 'identity.url'),
+        head: parseRef(value.head, 'identity.head'),
+        base: parseRef(value.base, 'identity.base')
+    };
+}
+function decodeLegacyIdentity(value) {
+    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')
+    };
+    return {
+        resource: { kind: 'number', value: legacy.number },
+        repository: legacy.repository,
+        url: legacy.url,
+        head: legacy.head,
+        base: legacy.base
+    };
+}
+function provenanceForSource(source) { return source === 'created' ? 'create-post' : source === 'reused' ? 'reuse' : source; }
+function parseFact(value, runtimeVersion = VERSION) {
+    if (!isRecord(value))
+        throw factError('fact must be an object');
+    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: 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');
+        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) || !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 = ['created', 'reused', 'explicit-bind', 'external-unique', 'external-explicit'];
+    if (!sources.includes(value.binding.source))
+        throw factError('binding source is invalid');
+    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 = 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');
+    exactKeys(value.provenance, ['establishedBy'], 'provenance');
+    const provenances = ['create-post', 'reuse', 'explicit-bind', 'external-unique', 'external-explicit'];
+    if (!provenances.includes(value.provenance.establishedBy))
+        throw factError('provenance.establishedBy is invalid');
+    if (value.provenance.establishedBy !== provenanceForSource(value.binding.source))
+        throw factError('binding.source and provenance.establishedBy do not match');
+    return {
+        version: 2, state: 'bound', identity: canonicalIdentity(value.identity),
+        binding: { status: 'verified', source: value.binding.source, verifiedAt: timestamp(value.binding.verifiedAt, 'binding.verifiedAt'), issueIdentity, remoteState: value.binding.remoteState, mergedAt, mergeCommitSha },
+        provenance: { establishedBy: value.provenance.establishedBy }
+    };
+}
+function decodePrDeliveryFact(value, runtimeVersion = VERSION) {
+    if (typeof value === 'string') {
+        let decoded;
+        try {
+            decoded = JSON.parse(value);
+        }
+        catch {
+            throw factError('value is not valid JSON');
+        }
+        return parseFact(decoded, runtimeVersion);
+    }
+    return parseFact(value, runtimeVersion);
+}
+function encodePrDeliveryFact(fact) { return JSON.stringify(parseFact(fact)); }
+function readPrDeliveryFact(metadata, runtimeVersion = VERSION) {
+    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], runtimeVersion) };
+    }
+    catch (error) {
+        return { status: 'invalid', fact: null, error: asFactError(error) };
+    }
+}
+function buildUnboundFact() { return { version: 2, state: 'unbound', reason: 'initial' }; }
+function buildSkippedFact(decidedAt) { return parseFact({ version: 2, state: 'skipped', reason: 'explicit', decidedAt }); }
+function buildBoundFact(input) {
+    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) { return { set: { [PR_DELIVERY_FACT_KEY]: encodePrDeliveryFact(fact) } }; }
+function identityFromPullRequest(pullRequest) {
+    return canonicalIdentity(pullRequest);
+}
+export { PR_DELIVERY_FACT_KEY, buildBoundFact, buildSkippedFact, buildUnboundFact, decodePrDeliveryFact, encodePrDeliveryFact, factFrontmatterMutation, identityFromPullRequest, readPrDeliveryFact, serializeResourceIdentity };
+//# sourceMappingURL=pr-delivery-fact.js.map

package/dist/lib/task/review-finalization.js

@@ -5,7 +5,7 @@ import { locateActivityLog, pairEntries, startedBackedRows } from './activity-lo
 import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { finalizeReviewSummaryContent } from './review-artifacts.js';
-import { inspectDecisionDetailDuplicates, repairDecisionDetailDuplicates } from './decision-details.js';
+import { inspectDecisionDetailDuplicates } from './decision-details.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { validateLifecycleExecution } from './lifecycle-execution.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
@@ -118,19 +118,15 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
         return failed(request, 'REVIEW_LEDGER_INVALID', `${ledgerError.code}: ${ledgerError.message}`, resolved.taskId);
     }
     const stageStatus = summarizeLedgerStage(rows, stage);
-    const repaired = repairDecisionDetailDuplicates(artifactContent);
-    if (!repaired.ok) {
-        return failed(request, 'REVIEW_DECISION_DETAIL_INVALID', `${repaired.code}: ${repaired.message}`, resolved.taskId, stageStatus);
-    }
-    const detailInspection = inspectDecisionDetailDuplicates(repaired.content);
+    const detailInspection = inspectDecisionDetailDuplicates(artifactContent);
     if (!detailInspection.ok) {
         return failed(request, 'REVIEW_DECISION_DETAIL_INVALID', `${detailInspection.code}: ${detailInspection.message}`, resolved.taskId, stageStatus);
     }
-    const transformed = finalizeReviewSummaryContent(repaired.content, stageStatus.unresolvedFindingCounts);
+    const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
     if (!transformed.ok) {
         return failed(request, transformed.code, transformed.message, resolved.taskId, stageStatus);
     }
-    if (!repaired.changed && !transformed.changed) {
+    if (!transformed.changed) {
         return {
             ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
             status: 'no-op',

package/dist/lib/task/review-fingerprint.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { artifactName, maxRound } from "./review-artifacts.js";
+import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from "./invalidation.js";
 const REVIEWED_TREE_RE = /^[a-f0-9]{40,64}$/;
 export function parseReviewedGitTree(value) {
     return REVIEWED_TREE_RE.test(value) ? value : null;
@@ -30,20 +31,49 @@ export function findAuthoritativeReviewCodeArtifact(taskDir) {
     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;
+    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
     };
 }
 export function extractReviewBaseline(content) {
     const match = String(content).match(/^[-*]?\s*\*\*(?:审查基线提交|Review Baseline Commit)\*\*[:：]\s*(.*?)\s*$/m);
     return match ? match[1].trim().replace(/`/g, "") : "";
 }
+export function extractReviewTargetHead(content) {
+    const match = String(content).match(/^[-*]?\s*\*\*(?:审查目标提交|审查目标 HEAD|Review Target Commit|Review Target Head)\*\*[:：]\s*(.*?)\s*$/m);
+    return match ? match[1].trim().replace(/`/g, "") : "";
+}
+export function extractReviewedHead(content) {
+    const match = String(content).match(/^[-*]?\s*\*\*(?:审查已检视提交|已检视提交|Reviewed Head Commit|Reviewed Head)\*\*[:：]\s*(.*?)\s*$/m);
+    return match ? match[1].trim().replace(/`/g, "") : "";
+}
 export function extractReviewDiffBase(content) {
     const match = String(content).match(/^[-*]?\s*\*\*(?:审查差异基线|Reviewed Diff Base)\*\*[:：]\s*(.*?)\s*$/m);
     return match ? match[1].trim().replace(/`/g, "") : "";