@fitlab-ai/agent-infra 0.9.12 → 0.9.13

package/dist/lib/task/events.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { appendActivityEntry, locateActivityLog, pairEntries, startedBackedRows } from './activity-log.js';
 import { buildArtifactLinkSection, artifactName, inspectArtifactDirectory, parseReviewedInputReference, parseCodePlanInputReference, parseArtifactName, resolveArtifactContext, validateCompletedArtifact } from './artifact-lifecycle.js';
-import { ArtifactReceiptError, sha256File, upsertArtifactReceipt } from './artifact-receipts.js';
+import { ArtifactReceiptError, parseArtifactReceipts, sha256File, upsertArtifactReceipt } from './artifact-receipts.js';
 import { parseTypedTaskFrontmatter } from './frontmatter.js';
 import { consumeImplementationInput, IMPLEMENTATION_INPUT_ALIASES, parseImplementationInputs, renderImplementationInputs } from './implementation-inputs.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
@@ -13,6 +14,11 @@ import { commitOrchestrationStageCompletion } from './orchestration.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
 import { allowsManualOverride } from './guard-override.js';
+import { LOCAL_ARTIFACT_REQUIRED_PATTERNS, LOCAL_ARTIFACT_REQUIRED_SECTIONS, consumeLocalArtifactFinalizationIntent, readLocalArtifactFinalizationIntent, validateLocalArtifact } from './local-artifact-finalization.js';
+import { loadVerificationConfig } from './verification-config.js';
+import { buildLifecycleFacts, canStart } from './capabilities.js';
+import { createInvalidationOperation, invalidationMutation, parseInvalidationDocument, targetIdFor, upsertInvalidation } from './invalidation.js';
+import { consumeReworkIntents, parseReworkIntentDocument, reworkIntentMutation, supersedeReworkIntents } from './rework-intent.js';
 const eventCatalog = [
     'analyze.started', 'analyze.awaiting-input', 'analyze.completed',
     'review-analysis.started', 'review-analysis.completed',
@@ -23,19 +29,19 @@ const eventCatalog = [
     'manual-validation.started', 'manual-validation.completed',
     'validation-run.started', 'validation-run.completed'
 ];
-const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope']);
+const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope', 'initiator', 'requestId', 'reasonCode', 'sourceFinding', 'sourceArtifact', 'sourceSha256']);
 const SCHEMAS = {
     'analyze.started': { optional: ['round'] },
     'analyze.awaiting-input': { required: ['question'] },
-    'analyze.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
+    'analyze.completed': { required: ['artifact', 'artifactSha256', 'semanticDigest'], optional: ['round', 'orchestrated'] },
     'review-analysis.started': { optional: ['round'] },
     'review-analysis.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
     'plan.started': { optional: ['round'] },
-    'plan.completed': { required: ['artifact'], optional: ['round', 'orchestrated'] },
+    'plan.completed': { required: ['artifact', 'artifactSha256', 'semanticDigest'], optional: ['round', 'orchestrated'] },
     'review-plan.started': { optional: ['round'] },
     'review-plan.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
     'code.started': { optional: ['round', 'fixFor', 'implementationInput'] },
-    'code.completed': { required: ['artifact'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation', 'orchestrated'] },
+    'code.completed': { required: ['artifact', 'artifactSha256', 'semanticDigest'], optional: ['round', 'fixFor', 'implementationInput', 'filesModified', 'testsPassed', 'blockers', 'major', 'minor', 'manualValidation', 'orchestrated'] },
     'review-code.started': { optional: ['round'] },
     'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
     'manual-validation.started': { optional: ['round'] },
@@ -43,6 +49,31 @@ const SCHEMAS = {
     'validation-run.started': { optional: ['round'] },
     'validation-run.completed': { required: ['artifact'], optional: ['round'] }
 };
+function localArtifactValidationConfig(repoRoot, family) {
+    const fallback = {
+        requiredSections: LOCAL_ARTIFACT_REQUIRED_SECTIONS[family],
+        requiredPatterns: LOCAL_ARTIFACT_REQUIRED_PATTERNS
+    };
+    const skillName = family === 'analysis' ? 'analyze-task' : family === 'plan' ? 'plan-task' : 'code-task';
+    try {
+        const artifact = loadVerificationConfig(repoRoot, skillName).checks.artifact;
+        if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact))
+            return fallback;
+        const sections = artifact.required_sections;
+        const patterns = artifact.required_patterns;
+        return {
+            requiredSections: Array.isArray(sections)
+                ? sections.filter((value) => typeof value === 'string')
+                : fallback.requiredSections,
+            requiredPatterns: Array.isArray(patterns)
+                ? patterns.filter((value) => typeof value === 'string')
+                : fallback.requiredPatterns
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
 function validateTaskEventRequest(request) {
     if (!eventCatalog.includes(request.event))
         return { code: 'EVENT_UNKNOWN', message: `unknown task event '${request.event}'` };
@@ -65,6 +96,18 @@ function validateTaskEventRequest(request) {
     }
     if (request.verdict && !['approved', 'changes-requested', 'rejected'].includes(request.verdict))
         return { code: 'EVENT_PAYLOAD_INVALID', message: 'verdict is invalid' };
+    if (request.initiator && !['human', 'model', 'orchestrator'].includes(request.initiator))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'initiator is invalid' };
+    if (request.requestId !== undefined && (!request.requestId.trim() || /[\r\n]/.test(request.requestId)))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'requestId must be a non-empty single line' };
+    if (request.reasonCode && !['user-request', 'new-requirement', 'upstream-fact-doubt', 'review-finding', 'retry', 'validation-rerun'].includes(request.reasonCode))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'reasonCode is invalid' };
+    for (const [name, value] of [['sourceFinding', request.sourceFinding], ['sourceArtifact', request.sourceArtifact], ['sourceSha256', request.sourceSha256]]) {
+        if (value !== undefined && (!value.trim() || /[\r\n]/.test(value)))
+            return { code: 'EVENT_PAYLOAD_INVALID', message: `${name} must be a non-empty single line` };
+    }
+    if (request.sourceSha256 !== undefined && !/^[a-f0-9]{64}$/.test(request.sourceSha256))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'sourceSha256 must be a sha256 digest' };
     if (request.event === 'code.completed') {
         const fix = request.fixFor !== undefined || ['blockers', 'major', 'minor', 'manualValidation'].some((key) => request[key] !== undefined);
         const modeRequired = fix ? ['fixFor', 'blockers', 'major', 'minor', 'manualValidation'] : ['filesModified', 'testsPassed'];
@@ -76,21 +119,30 @@ function validateTaskEventRequest(request) {
         return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor must reference a canonical review-code artifact' };
     if (request.implementationInput && !/^II-[1-9]\d*$/.test(request.implementationInput))
         return { code: 'EVENT_PAYLOAD_INVALID', message: 'implementationInput must be a canonical II-N id' };
+    if (request.artifactSha256 !== undefined && !/^[0-9a-f]{64}$/i.test(request.artifactSha256))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'artifactSha256 must be a 64-character hexadecimal digest' };
+    if (request.semanticDigest !== undefined && !/^[0-9a-f]{64}$/i.test(request.semanticDigest))
+        return { code: 'EVENT_PAYLOAD_INVALID', message: 'semanticDigest must be a 64-character hexadecimal digest' };
     if (request.fixFor && request.implementationInput)
         return { code: 'EVENT_PAYLOAD_INVALID', message: 'fixFor and implementationInput are mutually exclusive' };
     if (request.summaryResult !== undefined && (!request.summaryResult.trim() || /[\r\n]/.test(request.summaryResult)))
         return { code: 'EVENT_PAYLOAD_INVALID', message: 'summaryResult must be a non-empty single line' };
+    if (request.event !== 'analyze.awaiting-input' && /\.(?:started|completed)$/.test(request.event)) {
+        if (!request.initiator || !request.requestId || !request.reasonCode) {
+            return { code: 'EVENT_TRIGGER_REQUIRED', message: `${request.event} requires --initiator, --request-id, and --reason-code` };
+        }
+    }
     return null;
 }
 const FAMILY = {
-    analyze: { artifact: 'analysis', started: ['requirement-analysis', 'requirement-analysis-review', 'code'], completed: ['requirement-analysis', 'requirement-analysis-review', 'code'], target: 'requirement-analysis', label: 'Analyze Task' },
-    'review-analysis': { artifact: 'review-analysis', started: ['requirement-analysis', 'requirement-analysis-review'], completed: ['requirement-analysis', 'requirement-analysis-review'], target: 'requirement-analysis-review', label: 'Review Analysis' },
-    plan: { artifact: 'plan', started: ['requirement-analysis-review', 'technical-design-review', 'commit'], completed: ['requirement-analysis-review', 'technical-design-review', 'commit'], target: 'technical-design', label: 'Plan Task' },
-    'review-plan': { artifact: 'review-plan', started: ['technical-design', 'technical-design-review'], completed: ['technical-design', 'technical-design-review'], target: 'technical-design-review', label: 'Review Plan' },
-    code: { artifact: 'code', started: ['technical-design-review', 'code-review'], completed: ['technical-design-review', 'code-review'], target: 'code', label: 'Code Task' },
-    'review-code': { artifact: 'review-code', started: ['code', 'code-review', 'commit'], completed: ['code', 'code-review', 'commit'], target: 'code-review', label: 'Review Code' },
-    'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' },
-    'validation-run': { artifact: 'validation-run', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Run Manual Validation' }
+    analyze: { artifact: 'analysis', target: 'requirement-analysis', label: 'Analyze Task' },
+    'review-analysis': { artifact: 'review-analysis', target: 'requirement-analysis-review', label: 'Review Analysis' },
+    plan: { artifact: 'plan', target: 'technical-design', label: 'Plan Task' },
+    'review-plan': { artifact: 'review-plan', target: 'technical-design-review', label: 'Review Plan' },
+    code: { artifact: 'code', target: 'code', label: 'Code Task' },
+    'review-code': { artifact: 'review-code', target: 'code-review', label: 'Review Code' },
+    'manual-validation': { artifact: 'manual-validation', target: null, label: 'Complete Manual Validation' },
+    'validation-run': { artifact: 'validation-run', target: null, label: 'Run Manual Validation' }
 };
 const REVIEW_LEDGER_STAGES = {
     'review-analysis': 'analysis',
@@ -248,6 +300,124 @@ function openStartedIdentity(rows, family) {
 function reviewInputFamily(family) {
     return family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code';
 }
+function lifecycleAction(family) {
+    return family === 'analyze' ? 'analysis' : family;
+}
+function eventTrigger(request, family) {
+    return {
+        initiator: request.initiator ?? (request.orchestrated ? 'orchestrator' : request.agent === 'human' ? 'human' : 'model'),
+        requestId: request.requestId ?? `${request.taskRef}:${request.event}:${request.round ?? 1}`,
+        requestedAction: lifecycleAction(family),
+        reasonCode: request.reasonCode ?? (request.fixFor || request.implementationInput ? 'review-finding' : 'user-request'),
+        ...(request.sourceFinding ? { sourceFinding: request.sourceFinding } : {}),
+        ...(request.sourceArtifact ? { sourceArtifact: request.sourceArtifact } : {}),
+        ...(request.sourceSha256 ? { sourceSha256: request.sourceSha256 } : {}),
+        ...(request.implementationInput ? { implementationInput: request.implementationInput } : {}),
+        explicitRequest: request.requestId !== undefined || request.reasonCode !== undefined || request.initiator !== undefined || request.orchestrated === true
+    };
+}
+function invalidationMutationForCompletion(content, taskDir, family, artifact, timestamp) {
+    if (!['analyze', 'plan', 'code'].includes(family))
+        return { mutation: null };
+    const parsed = parseInvalidationDocument(content);
+    if (!parsed.ok)
+        return { error: parsed.message };
+    const downstream = {
+        analyze: ['review-analysis', 'plan', 'review-plan', 'code', 'review-code'],
+        plan: ['review-plan', 'code', 'review-code'],
+        code: ['review-code']
+    };
+    const sourceFamily = family;
+    let receipts = [];
+    try {
+        receipts = parseArtifactReceipts(content).rows;
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+    const targets = downstream[sourceFamily].flatMap((targetFamily) => {
+        const names = fs.readdirSync(taskDir).filter((name) => {
+            const pattern = targetFamily === 'review-analysis' ? /^review-analysis(?:-r\d+)?\.md$/
+                : targetFamily === 'review-plan' ? /^review-plan(?:-r\d+)?\.md$/
+                    : targetFamily === 'review-code' ? /^review-code(?:-r\d+)?\.md$/
+                        : new RegExp(`^${targetFamily}(?:-r\\d+)?\\.md$`);
+            return pattern.test(name);
+        });
+        return names.flatMap((name) => {
+            try {
+                const stat = fs.lstatSync(path.join(taskDir, name));
+                if (!stat.isFile() || stat.isSymbolicLink())
+                    return [];
+                const targetRound = parseArtifactName(name)?.round ?? 1;
+                const targetSha256 = sha256File(path.join(taskDir, name));
+                const shapes = [
+                    { targetKind: 'artifact', targetFamily, targetArtifact: name, targetRound, targetSha256 }
+                ];
+                const receipt = receipts.find((candidate) => candidate.output === name);
+                if (receipt)
+                    shapes.push({
+                        targetKind: 'receipt', targetFamily, targetArtifact: name, targetRound,
+                        targetSha256: receipt.inputSha256
+                    });
+                if (targetFamily.startsWith('review-')) {
+                    shapes.push({ targetKind: 'approval', targetFamily, targetArtifact: name, targetRound, targetSha256 });
+                }
+                if (targetFamily === 'review-code') {
+                    shapes.push({ targetKind: 'reviewed-snapshot', targetFamily, targetArtifact: name, targetRound, targetSha256 });
+                }
+                return shapes.map((targetShape) => ({
+                    ...targetShape,
+                    targetId: targetIdFor('pending', targetShape), operationId: 'pending', status: 'pending',
+                    reasonCode: 'upstream-replaced', updatedAt: timestamp
+                }));
+            }
+            catch (error) {
+                throw new Error(`cannot inspect invalidation target '${name}': ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    });
+    if (targets.length === 0)
+        return { mutation: null };
+    const source = {
+        sourceFamily: lifecycleAction(family), sourceArtifact: artifact.name,
+        sourceRound: parseArtifactName(artifact.name)?.round ?? 1, sourceSha256: sha256File(artifact.path),
+        createdAt: timestamp, updatedAt: timestamp
+    };
+    const operation = createInvalidationOperation(source);
+    const normalizedTargets = targets.map((target) => ({
+        ...target, operationId: operation.operationId,
+        targetId: targetIdFor(operation.operationId, target)
+    }));
+    const operationWithTotal = createInvalidationOperation(source, normalizedTargets);
+    const next = upsertInvalidation(parsed.document, operationWithTotal, normalizedTargets);
+    if (!next.ok)
+        return { error: next.message };
+    return { mutation: next.changed ? invalidationMutation(content, next.document) : null };
+}
+function reworkIntentMutationForCompletion(content, taskDir, family, artifact, timestamp) {
+    const parsed = parseReworkIntentDocument(content);
+    if (!parsed.ok)
+        return { error: parsed.message };
+    const hash = sha256File(artifact.path);
+    let next = parsed.intents;
+    if (family === 'analyze' || family === 'plan' || family === 'code') {
+        const hashes = Object.fromEntries(fs.readdirSync(taskDir).flatMap((name) => {
+            if (!/^review-(?:analysis|plan|code)(?:-r\d+)?\.md$/.test(name))
+                return [];
+            try {
+                return [[name, sha256File(path.join(taskDir, name))]];
+            }
+            catch {
+                return [];
+            }
+        }));
+        next = consumeReworkIntents(next, family === 'analyze' ? 'analysis' : family, hashes, timestamp).intents;
+    }
+    if (family === 'review-analysis' || family === 'review-plan' || family === 'review-code') {
+        next = supersedeReworkIntents(next, artifact.name, hash, timestamp).intents;
+    }
+    return { mutation: JSON.stringify(next) === JSON.stringify(parsed.intents) ? null : reworkIntentMutation(content, next) };
+}
 function buildCompletionReceipt(taskDir, family, artifact, completedAt, frontmatter) {
     if (family === 'code') {
         let content;
@@ -399,6 +569,7 @@ function applyTaskEventUnlocked(request, options = {}) {
     const completedRows = matchingRows.filter((item) => item.done);
     const row = manual ? openRows.at(-1) : matchingRows[0];
     let completedArtifact = null;
+    let localFinalizationIntent = null;
     if (eventIdentity.phase === 'started' && row) {
         if (row.agent !== normalized.agent)
             return failed(normalized, { code: 'EVENT_LOG_CONFLICT', message: 'open started event has a different agent' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
@@ -418,14 +589,83 @@ function applyTaskEventUnlocked(request, options = {}) {
         if (!validated.ok)
             return failed(normalized, validated.error, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
         completedArtifact = validated.artifact;
+        if (eventIdentity.family === 'analyze' || eventIdentity.family === 'plan' || eventIdentity.family === 'code') {
+            const localFamily = eventIdentity.family === 'analyze'
+                ? 'analysis'
+                : eventIdentity.family === 'plan' ? 'plan' : 'code';
+            let artifactContent;
+            try {
+                artifactContent = fs.readFileSync(completedArtifact.path, 'utf8');
+            }
+            catch (error) {
+                return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot read ${completedArtifact.name}: ${String(error)}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+            }
+            const validationConfig = localArtifactValidationConfig(resolved.repoRoot, localFamily);
+            const local = validateLocalArtifact(artifactContent, {
+                family: localFamily,
+                requiredSections: validationConfig.requiredSections,
+                requiredPatterns: validationConfig.requiredPatterns
+            });
+            if (!local.ok) {
+                return failed(normalized, {
+                    code: 'EVENT_ARTIFACT_CONFLICT',
+                    message: `LOCAL_ARTIFACT_INVALID: ${local.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ')}`
+                }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+            }
+            const actualSha256 = sha256File(completedArtifact.path);
+            if (actualSha256 !== normalized.artifactSha256) {
+                return failed(normalized, {
+                    code: 'EVENT_ARTIFACT_CONFLICT',
+                    message: `artifact SHA-256 does not match finalizer result for ${completedArtifact.name}`
+                }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+            }
+            if (local.semanticDigest !== normalized.semanticDigest) {
+                return failed(normalized, {
+                    code: 'EVENT_ARTIFACT_CONFLICT',
+                    message: `semantic digest does not match finalizer result for ${completedArtifact.name}`
+                }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+            }
+            try {
+                localFinalizationIntent = readLocalArtifactFinalizationIntent(resolved.repoRoot, resolved.taskId, localFamily, completedArtifact.name);
+            }
+            catch (error) {
+                return failed(normalized, {
+                    code: 'EVENT_ARTIFACT_CONFLICT',
+                    message: `cannot read local finalizer provenance for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
+                }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+            }
+            if (!localFinalizationIntent || !['passed', 'consumed'].includes(localFinalizationIntent.state)) {
+                return failed(normalized, {
+                    code: 'EVENT_ARTIFACT_CONFLICT',
+                    message: `local finalizer provenance is missing or incomplete for ${completedArtifact.name}`
+                }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+            }
+            if (localFinalizationIntent.artifactSha256 !== actualSha256 || localFinalizationIntent.semanticDigest !== local.semanticDigest) {
+                return failed(normalized, {
+                    code: 'EVENT_ARTIFACT_CONFLICT',
+                    message: `local finalizer provenance does not match ${completedArtifact.name}`
+                }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+            }
+        }
     }
     if (eventIdentity.phase === 'waiting' && section.entries.some((entry) => entry.step === eventIdentity.action && entry.note === eventIdentity.note)) {
         const existing = section.entries.find((entry) => entry.step === eventIdentity.action && entry.note === eventIdentity.note);
         return successNoOp(normalized, resolved.taskId, resolved.taskMdPath, currentStep, eventIdentity, existing.time, frontmatter, artifactContext);
     }
-    const allowed = FAMILY[eventIdentity.family][eventIdentity.phase === 'started' ? 'started' : 'completed'];
-    if (!allowed.includes(currentStep) && !allowsManualOverride(options.manualOverride, 'task-event', 'EVENT_TRANSITION_INVALID'))
-        return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${normalized.event} is not allowed from '${currentStep}'` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    if (eventIdentity.phase === 'started') {
+        const trigger = eventTrigger(normalized, eventIdentity.family);
+        const facts = buildLifecycleFacts(resolved.taskDir, content, resolved.state);
+        if (!facts.ok)
+            return failed(normalized, { code: 'EVENT_TRANSITION_INVALID', message: `${facts.code}: ${facts.message}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+        const capability = canStart(lifecycleAction(eventIdentity.family), facts.facts, trigger);
+        const capabilityOverride = capability.reasonCode === 'TASK_NOT_ACTIVE'
+            ? stateOverride
+            : allowsManualOverride(options.manualOverride, 'task-event', 'EVENT_TRANSITION_INVALID');
+        if (!capability.allowed && !capabilityOverride) {
+            const code = capability.reasonCode === 'INVALIDATION_INCOMPLETE' ? 'TASK_INVALIDATION_BLOCKED' : 'EVENT_TRANSITION_INVALID';
+            return failed(normalized, { code, message: `${capability.reasonCode}: ${capability.evidence.join(', ')}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+        }
+    }
     const findingCountError = validateReviewFindingCounts(normalized, content, eventIdentity.family, completedArtifact?.path ?? null);
     if (findingCountError)
         return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
@@ -459,12 +699,27 @@ function applyTaskEventUnlocked(request, options = {}) {
         return failed(normalized, { code: 'METADATA_CAPTURE_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
     }
     let completionReceipt = null;
+    let completionInvalidation = null;
+    let completionRework = null;
     if (eventIdentity.phase === 'completed' && completedArtifact) {
         const receipt = buildCompletionReceipt(resolved.taskDir, eventIdentity.family, completedArtifact, metadata.timestamp, frontmatter);
         if (receipt && !receipt.ok) {
             return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: receipt.message }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
         }
         completionReceipt = receipt?.receipt ?? null;
+        try {
+            const invalidation = invalidationMutationForCompletion(content, resolved.taskDir, eventIdentity.family, completedArtifact, metadata.timestamp);
+            if ('error' in invalidation)
+                return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: invalidation.error }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+            completionInvalidation = invalidation.mutation;
+            const rework = reworkIntentMutationForCompletion(content, resolved.taskDir, eventIdentity.family, completedArtifact, metadata.timestamp);
+            if ('error' in rework)
+                return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: rework.error }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+            completionRework = rework.mutation;
+        }
+        catch (error) {
+            return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: error instanceof Error ? error.message : String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+        }
     }
     const step = eventIdentity.phase === 'started' || eventIdentity.target === null ? currentStep : eventIdentity.target;
     const logStep = eventIdentity.phase === 'started' ? `${eventIdentity.action} [started]` : eventIdentity.action;
@@ -521,6 +776,10 @@ function applyTaskEventUnlocked(request, options = {}) {
             return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
         }
     }
+    if (completionInvalidation)
+        mutations.push(completionInvalidation);
+    if (completionRework)
+        mutations.push(completionRework);
     if (eventIdentity.phase === 'completed' && normalized.implementationInput) {
         let implementationRows;
         try {
@@ -536,7 +795,28 @@ function applyTaskEventUnlocked(request, options = {}) {
         });
     }
     mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body });
-    const result = writeTask({ taskRef: normalized.taskRef, expectedState: stateOverride ? resolved.state : 'active', dryRun: normalized.dryRun, mutations }, { ...options, metadataProvider: () => metadata });
+    if (!normalized.dryRun && localFinalizationIntent && completedArtifact && localFinalizationIntent.state === 'passed') {
+        try {
+            localFinalizationIntent = consumeLocalArtifactFinalizationIntent(resolved.repoRoot, localFinalizationIntent);
+        }
+        catch (error) {
+            return failed(normalized, {
+                code: 'EVENT_ARTIFACT_CONFLICT',
+                message: `local finalizer provenance could not be consumed before task write for ${completedArtifact.name}: ${error instanceof Error ? error.message : String(error)}`
+            }, {
+                taskId: resolved.taskId,
+                taskMdPath: resolved.taskMdPath,
+                fromStep: currentStep,
+                toStep: step,
+                action: eventIdentity.action,
+                phase: eventIdentity.phase,
+                artifactContext
+            });
+        }
+    }
+    const sourceCompletion = eventIdentity.phase === 'completed'
+        && ['analyze', 'plan', 'code'].includes(eventIdentity.family);
+    const result = writeTask({ taskRef: normalized.taskRef, expectedState: stateOverride ? resolved.state : 'active', dryRun: normalized.dryRun, mutations }, { ...options, invalidationContext: sourceCompletion ? 'source-completion' : 'standard', metadataProvider: () => metadata });
     if (result.status === 'failed')
         return failed(normalized, result.error, { taskId: result.taskId, taskMdPath: result.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, timestamp: result.timestamp, agentInfraVersion: result.agentInfraVersion, operations: result.operations, artifactContext });
     if (!normalized.dryRun && orchestrationCompletion) {

package/dist/lib/task/finalization.js

@@ -42,7 +42,7 @@ function failed(taskId, error, overrides = {}) {
         ...overrides
     };
 }
-function emptyReceipt(taskId) {
+function emptyReceipt(taskId, controlBinding) {
     return {
         version: RECEIPT_VERSION,
         taskId,
@@ -54,6 +54,7 @@ function emptyReceipt(taskId) {
         verification: 'pending',
         warningProjection: 'done',
         warnings: [],
+        ...(controlBinding ? { controlBinding } : {}),
         updatedAt: now(),
         lastError: null
     };
@@ -79,6 +80,7 @@ function validateReceipt(value, taskId) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('receipt must be an object');
     const receipt = value;
+    const controlBinding = receipt.controlBinding;
     const states = ['pending', 'done', 'skipped'];
     if (receipt.version !== RECEIPT_VERSION || receipt.taskId !== taskId || receipt.intent !== 'complete'
         || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
@@ -89,7 +91,11 @@ function validateReceipt(value, taskId) {
         || !['pending', 'done'].includes(String(receipt.warningProjection))
         || !Array.isArray(receipt.warnings) || receipt.warnings.some((warning) => !validWarning(warning))
         || typeof receipt.updatedAt !== 'string'
-        || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError))))
+        || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)))
+        || (receipt.controlBinding !== undefined && (!controlBinding || typeof controlBinding !== 'object'
+            || Array.isArray(controlBinding)
+            || typeof controlBinding.generation !== 'string' || controlBinding.generation.length === 0
+            || typeof controlBinding.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(controlBinding.requestId))))
         throw new Error('receipt schema is invalid');
     return receipt;
 }
@@ -100,6 +106,13 @@ function readReceipt(repoRoot, taskId) {
     const value = JSON.parse(fs.readFileSync(file, 'utf8'));
     return validateReceipt(value, taskId);
 }
+function readTaskFinalizationReceipt(repoRoot, taskId) {
+    return readReceipt(path.resolve(repoRoot), taskId);
+}
+function controlBindingMatches(receipt, binding) {
+    return receipt.controlBinding?.generation === binding.generation
+        && receipt.controlBinding.requestId === binding.requestId;
+}
 function writeReceipt(repoRoot, receipt) {
     const directory = finalizationRoot(repoRoot);
     fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
@@ -346,7 +359,7 @@ function reconcileWarningProjection(repoRoot, taskId, receipt, consumed) {
         return receipt;
     }
 }
-function syncPendingTaskComment(input) {
+async function syncPendingTaskComment(input) {
     const { repoRoot, taskId, agent, commentSync, consumedCapabilities } = input;
     let receipt = input.receipt;
     if (receipt.taskComment !== 'pending') {
@@ -358,7 +371,7 @@ function syncPendingTaskComment(input) {
         };
     }
     try {
-        const result = commentSync(taskId, { kind: 'task', agent, cwd: repoRoot });
+        const result = await commentSync(taskId, { kind: 'task', agent, cwd: repoRoot });
         const step = commentStep(result);
         if (result.status === 'applied' || result.status === 'no-op') {
             const skipped = result.error?.code === 'ISSUE_NOT_LINKED';
@@ -416,7 +429,7 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
         error: hardError ? error : postLifecyclePending ? null : error
     };
 }
-function applyUnderLock(request, taskId, options) {
+async function applyUnderLock(request, taskId, options) {
     const repoRoot = path.resolve(options.repoRoot);
     const lifecycle = options.lifecycle ?? applyTaskLifecycle;
     const commentSync = options.commentSync ?? syncPlatformComment;
@@ -426,17 +439,28 @@ function applyUnderLock(request, taskId, options) {
     try {
         const file = receiptPath(repoRoot, taskId);
         const existed = fs.existsSync(file);
-        receipt = readReceipt(repoRoot, taskId) ?? emptyReceipt(taskId);
+        receipt = readReceipt(repoRoot, taskId) ?? emptyReceipt(taskId, options.controlBinding);
         if (!existed)
             writeReceipt(repoRoot, receipt);
     }
     catch (error) {
         return failed(taskId, errorOf(error, 'TASK_FINALIZATION_RECEIPT_INVALID'));
     }
+    if (options.controlBinding && !controlBindingMatches(receipt, options.controlBinding)) {
+        const error = {
+            code: 'TASK_FINALIZATION_CONTROL_BINDING_CONFLICT',
+            message: 'finalization receipt belongs to a different sandbox request or generation',
+            retryable: false
+        };
+        return failed(taskId, error, {
+            completedSteps: completedSteps(receipt),
+            pendingSteps: pendingSteps(receipt)
+        });
+    }
     const preflightState = resolveTaskRef(taskId, { repoRoot });
     if (options.preflight && preflightState.ok && preflightState.state === 'active') {
         try {
-            const preflight = options.preflight({ taskRef: taskId, event: 'complete-task.preflight' }, { repoRoot });
+            const preflight = await options.preflight({ taskRef: taskId, event: 'complete-task.preflight' }, { repoRoot });
             if (preflight.status !== 'pass') {
                 const detail = verificationFailure(preflight);
                 return failed(taskId, detail, {
@@ -510,7 +534,7 @@ function applyUnderLock(request, taskId, options) {
     }
     let taskComment = null;
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    const initialComment = syncPendingTaskComment({
+    const initialComment = await syncPendingTaskComment({
         repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
     });
     receipt = initialComment.receipt;
@@ -526,7 +550,7 @@ function applyUnderLock(request, taskId, options) {
             verification = { status: 'no-op', changed: false, error: null };
         }
         else {
-            const result = verify({ taskRef: taskId, event: 'complete-task.completed' }, { repoRoot });
+            const result = await verify({ taskRef: taskId, event: 'complete-task.completed' }, { repoRoot });
             verification = verificationStep(result);
             if (result.status === 'pass') {
                 const capability = issueCapability(receipt, 'verification');
@@ -534,7 +558,7 @@ function applyUnderLock(request, taskId, options) {
                     scope: 'verification', operation: 'succeeded'
                 }, consumedCapabilities);
                 receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-                const finalComment = syncPendingTaskComment({
+                const finalComment = await syncPendingTaskComment({
                     repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
                 });
                 receipt = finalComment.receipt;
@@ -571,7 +595,7 @@ function applyUnderLock(request, taskId, options) {
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
     return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification }, changed);
 }
-function applyTaskFinalization(request, options) {
+async function applyTaskFinalization(request, options) {
     if (request.intent !== 'complete' || !request.taskRef || !request.agent) {
         return failed(null, { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'complete finalization requires taskRef and agent', retryable: false });
     }
@@ -580,7 +604,7 @@ function applyTaskFinalization(request, options) {
     if (!resolved.ok)
         return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
     try {
-        return withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.complete', () => applyUnderLock(request, resolved.taskId, options));
+        return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.complete', () => applyUnderLock(request, resolved.taskId, options));
     }
     catch (error) {
         const detail = error instanceof TaskExecutionLockError
@@ -589,5 +613,5 @@ function applyTaskFinalization(request, options) {
         return failed(resolved.taskId, detail);
     }
 }
-export { applyFinalizationReceiptMutation, applyTaskFinalization, issueCapability as createFinalizationCapability };
+export { applyFinalizationReceiptMutation, applyTaskFinalization, issueCapability as createFinalizationCapability, readTaskFinalizationReceipt };
 //# sourceMappingURL=finalization.js.map