@fitlab-ai/agent-infra 0.10.0 → 0.11.1

package/dist/lib/task/events.js

@@ -1,13 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { appendActivityEntry, locateActivityLog, pairEntries, startedBackedRows } from './activity-log.js';
-import { buildArtifactLinkSection, inspectArtifactDirectory, parseReviewedInputReference, parseCodePlanInputReference, resolveArtifactContext, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { buildArtifactLinkSection, inspectArtifactDirectory, resolveArtifactContext, validateCompletedArtifact } from './artifact-lifecycle.js';
 import { artifactName, parseArtifactName } from './artifact-name.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';
 import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.js';
+import { extractReviewBaseline, extractReviewedHead, extractReviewedSnapshotTree } from './review-fingerprint.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { findSectionHeading } from './sections.js';
 import { validateLifecycleExecution } from './lifecycle-execution.js';
@@ -20,6 +22,7 @@ import { writeArtifactRecoveryIntent, readArtifactRecoveryIntent } from './artif
 import { reconcileArtifactRecovery, recoveryContextFromIntent, sha256Content } from './artifact-recovery.js';
 import { buildLifecycleFacts, canStart } from './capabilities.js';
 import { createInvalidationOperation, invalidationMutation, parseInvalidationDocument, targetIdFor, upsertInvalidation } from './invalidation.js';
+import { reconcileTaskInvalidation } from './invalidation-command.js';
 import { consumeReworkIntents, parseReworkIntentDocument, reworkIntentMutation, supersedeReworkIntents } from './rework-intent.js';
 import { ARTIFACT_FAMILIES, expectedQualificationRelations, parseQualificationAudit, parseTaskQualification, upstreamArtifactDigest, validateQualificationAudit } from './qualification-audit.js';
 import { getArtifactSchema } from './artifact-schema.js';
@@ -36,6 +39,27 @@ const eventCatalog = [
     'manual-validation.started', 'manual-validation.completed',
     'validation-run.started', 'validation-run.completed'
 ];
+function approvedCleanReviewedCommit(reviewContent, verdict, repoRoot) {
+    if (verdict !== 'approved')
+        return null;
+    const reviewedHead = extractReviewedHead(reviewContent) || extractReviewBaseline(reviewContent);
+    const reviewedTree = extractReviewedSnapshotTree(reviewContent);
+    if (!/^[a-f0-9]{40}$/.test(reviewedHead) || !/^[a-f0-9]{40}$/.test(reviewedTree))
+        return null;
+    try {
+        const currentHead = execFileSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+        if (currentHead !== reviewedHead)
+            return null;
+        const currentTree = execFileSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD^{tree}'], { encoding: 'utf8' }).trim();
+        if (currentTree !== reviewedTree)
+            return null;
+        execFileSync('git', ['-C', repoRoot, 'diff-index', '--quiet', 'HEAD', '--']);
+        return reviewedHead;
+    }
+    catch {
+        return null;
+    }
+}
 const BASE_FIELDS = new Set(['taskRef', 'event', 'agent', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope', 'initiator', 'requestId', 'reasonCode', 'sourceFinding', 'sourceArtifact', 'sourceSha256']);
 const SCHEMAS = {
     'analyze.started': { optional: ['round'] },
@@ -334,7 +358,7 @@ function reconcileReviewCompletionReplay(repoRoot, taskDir, taskId, family, arti
             }
             intent = reconciled.intent;
         }
-        if (!['passed', 'consumed'].includes(intent.state)) {
+        if (!['passed', 'consumption-started', 'consumed'].includes(intent.state)) {
             return {
                 code: 'EVENT_ARTIFACT_CONFLICT',
                 message: `review finalizer provenance is incomplete for ${artifact}`
@@ -345,9 +369,7 @@ function reconcileReviewCompletionReplay(repoRoot, taskDir, taskId, family, arti
             return { code: 'EVENT_ARTIFACT_CONFLICT', message: validated.error.message };
         }
         const content = fs.readFileSync(validated.artifact.path, 'utf8');
-        const expectedRequestId = `review-finalize:${taskId}:${stage}:${round}`;
         if (intent.round !== round
-            || intent.requestId !== expectedRequestId
             || intent.finalArtifactSha256 !== sha256Content(content)
             || intent.finalSemanticDigest !== canonicalSemanticDigest(content)) {
             return {
@@ -355,7 +377,7 @@ function reconcileReviewCompletionReplay(repoRoot, taskDir, taskId, family, arti
                 message: `review finalizer provenance does not match ${artifact}`
             };
         }
-        if (intent.state === 'passed') {
+        if (intent.state === 'passed' || intent.state === 'consumption-started') {
             const consumed = { ...intent, state: 'consumed', updatedAt: Date.now() };
             writeArtifactRecoveryIntent(repoRoot, consumed, { expected: intent });
         }
@@ -595,34 +617,22 @@ function reworkIntentMutationForCompletion(content, taskDir, family, artifact, t
 }
 function buildCompletionReceipt(taskDir, family, artifact, completedAt, frontmatter) {
     if (family === 'code') {
-        let content;
-        try {
-            content = fs.readFileSync(artifact.path, 'utf8');
-        }
-        catch (error) {
-            return { ok: false, message: `cannot read ${artifact.name}: ${String(error)}` };
-        }
-        const input = parseCodePlanInputReference(content);
-        if (!input)
-            return { ok: false, message: `${artifact.name} does not reference a canonical plan artifact` };
         const startedInput = typeof frontmatter.code_input_artifact === 'string' ? frontmatter.code_input_artifact : '';
         const startedSha256 = typeof frontmatter.code_input_sha256 === 'string' ? frontmatter.code_input_sha256 : '';
         if (!startedInput || !startedSha256)
             return { ok: false, message: 'code.started plan input context is missing' };
-        if (input.name !== startedInput)
-            return { ok: false, message: `${artifact.name} plan input '${input.name}' does not match code.started input '${startedInput}'` };
         const plan = inspectArtifactDirectory(taskDir, 'plan');
-        if (plan.status !== 'ready' || !plan.latest || plan.latest.name !== input.name) {
-            return { ok: false, message: `code input '${input.name}' is not the latest plan artifact` };
+        if (plan.status !== 'ready' || !plan.latest || plan.latest.name !== startedInput) {
+            return { ok: false, message: `code input '${startedInput}' is not the latest plan artifact` };
         }
         try {
             const inputSha256 = sha256File(plan.latest.path);
             if (inputSha256 !== startedSha256)
-                return { ok: false, message: `code input ${input.name} changed after code.started` };
+                return { ok: false, message: `code input ${startedInput} changed after code.started` };
             return {
                 ok: true,
                 receipt: {
-                    event: 'code.completed', output: artifact.name, input: input.name,
+                    event: 'code.completed', output: artifact.name, input: startedInput,
                     inputSha256, completedAt
                 }
             };
@@ -634,25 +644,13 @@ function buildCompletionReceipt(taskDir, family, artifact, completedAt, frontmat
     if (!family.startsWith('review-'))
         return null;
     const expectedFamily = reviewInputFamily(family);
-    let content;
-    try {
-        content = fs.readFileSync(artifact.path, 'utf8');
-    }
-    catch (error) {
-        return { ok: false, message: `cannot read ${artifact.name}: ${String(error)}` };
-    }
-    const input = parseReviewedInputReference(content, expectedFamily);
-    if (!input)
-        return { ok: false, message: `${artifact.name} does not reference a canonical ${expectedFamily} artifact` };
     const startedInput = typeof frontmatter.review_input_artifact === 'string' ? frontmatter.review_input_artifact : '';
     const startedSha256 = typeof frontmatter.review_input_sha256 === 'string' ? frontmatter.review_input_sha256 : '';
     if (!startedInput || !startedSha256)
         return { ok: false, message: 'review started input context is missing' };
-    if (input.name !== startedInput)
-        return { ok: false, message: `${artifact.name} input '${input.name}' does not match review.started input '${startedInput}'` };
     const current = inspectArtifactDirectory(taskDir, expectedFamily);
-    if (current.status !== 'ready' || !current.latest || current.latest.name !== input.name) {
-        return { ok: false, message: `review input '${input.name}' is not the latest ${expectedFamily} artifact` };
+    if (current.status !== 'ready' || !current.latest || current.latest.name !== startedInput) {
+        return { ok: false, message: `review input '${startedInput}' is not the latest ${expectedFamily} artifact` };
     }
     const event = family === 'review-analysis'
         ? 'review-analysis.completed'
@@ -663,17 +661,17 @@ function buildCompletionReceipt(taskDir, family, artifact, completedAt, frontmat
             throw new Error('review input is not a regular file');
         const inputSha256 = sha256File(current.latest.path);
         if (inputSha256 !== startedSha256)
-            return { ok: false, message: `review input ${input.name} changed after review.started` };
+            return { ok: false, message: `review input ${startedInput} changed after review.started` };
         return {
             ok: true,
             receipt: {
-                event, output: artifact.name, input: input.name,
+                event, output: artifact.name, input: startedInput,
                 inputSha256, completedAt
             }
         };
     }
     catch (error) {
-        return { ok: false, message: `cannot hash review input ${input.name}: ${error instanceof Error ? error.message : String(error)}` };
+        return { ok: false, message: `cannot hash review input ${startedInput}: ${error instanceof Error ? error.message : String(error)}` };
     }
 }
 function applyTaskEventUnlocked(request, options = {}) {
@@ -693,6 +691,24 @@ function applyTaskEventUnlocked(request, options = {}) {
     catch (error) {
         return failed(request, { code: 'TASK_READ_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
     }
+    const initialParts = eventParts(request.event);
+    if (initialParts.phase === 'started' && !request.dryRun) {
+        const reconciled = reconcileTaskInvalidation(request.taskRef, { repoRoot: resolved.repoRoot });
+        if (reconciled.status === 'failed') {
+            return failed(request, {
+                code: 'EVENT_TRANSITION_INVALID',
+                message: `INVALIDATION_RECONCILE_FAILED: ${reconciled.error?.code ?? 'UNKNOWN'}: ${reconciled.error?.message ?? ''}`
+            }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+        }
+        if (reconciled.changed) {
+            try {
+                content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+            }
+            catch (error) {
+                return failed(request, { code: 'TASK_READ_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
+            }
+        }
+    }
     let frontmatter;
     try {
         frontmatter = parseTypedTaskFrontmatter(content);
@@ -706,7 +722,6 @@ function applyTaskEventUnlocked(request, options = {}) {
     const rows = startedBackedRows(pairEntries(section.entries));
     let normalized = request;
     let artifactContext = null;
-    const initialParts = eventParts(request.event);
     if (initialParts.phase === 'started') {
         const openIdentity = openStartedIdentity(rows, initialParts.family);
         if (openIdentity && 'conflict' in openIdentity)
@@ -935,20 +950,15 @@ function applyTaskEventUnlocked(request, options = {}) {
                 if (reconciled.status === 'passed' || reconciled.status === 'consumed')
                     reviewFinalizationIntent = reconciled.intent;
             }
-            if (!reviewFinalizationIntent || !['passed', 'consumed'].includes(reviewFinalizationIntent.state)) {
+            if (!reviewFinalizationIntent || !['passed', 'consumption-started', 'consumed'].includes(reviewFinalizationIntent.state)) {
                 return failed(normalized, {
                     code: 'EVENT_ARTIFACT_CONFLICT',
                     message: `review 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 });
             }
-            const reviewStage = eventIdentity.family === 'review-analysis'
-                ? 'analysis'
-                : eventIdentity.family === 'review-plan' ? 'plan' : 'code';
             const actualSha256 = sha256File(completedArtifact.path);
             const actualSemanticDigest = canonicalSemanticDigest(reviewContent);
-            const expectedRequestId = `review-finalize:${resolved.taskId}:${reviewStage}:${normalized.round}`;
             if (reviewFinalizationIntent.round !== normalized.round
-                || reviewFinalizationIntent.requestId !== expectedRequestId
                 || reviewFinalizationIntent.finalArtifactSha256 !== actualSha256
                 || reviewFinalizationIntent.finalSemanticDigest !== actualSemanticDigest) {
                 return failed(normalized, {
@@ -1060,6 +1070,13 @@ function applyTaskEventUnlocked(request, options = {}) {
     else if (eventIdentity.phase === 'completed' && eventIdentity.family.startsWith('review-')) {
         frontmatterRemove = ['review_input_artifact', 'review_input_sha256'];
     }
+    if (eventIdentity.phase === 'completed' && eventIdentity.family === 'review-code' && reviewContent !== null) {
+        const reviewedCommit = approvedCleanReviewedCommit(reviewContent, normalized.verdict, resolved.repoRoot);
+        if (reviewedCommit)
+            frontmatterSet.last_reviewed_commit = reviewedCommit;
+        else if (normalized.verdict === 'approved')
+            frontmatterSet.last_reviewed_commit = '';
+    }
     if (eventIdentity.phase === 'completed')
         frontmatterRemove = [...(frontmatterRemove ?? []), 'qualification_input_relations'];
     if (eventIdentity.phase === 'started' && normalized.implementationInput)
@@ -1106,7 +1123,7 @@ function applyTaskEventUnlocked(request, options = {}) {
                 const expectedIntent = localFinalizationIntent;
                 localFinalizationIntent = {
                     ...localFinalizationIntent,
-                    state: 'commit-started',
+                    state: 'consumption-started',
                     phase: 'task-event.completed',
                     authorityDigest: lifecycleRecoveryAttestationDigest(lifecycleAuthority),
                     requestId: lifecycleAuthority.lifecycleRequestId,
@@ -1138,7 +1155,7 @@ function applyTaskEventUnlocked(request, options = {}) {
             const expectedIntent = reviewFinalizationIntent;
             reviewFinalizationIntent = {
                 ...reviewFinalizationIntent,
-                state: 'commit-started',
+                state: 'consumption-started',
                 phase: 'task-event.completed',
                 updatedAt: Date.now()
             };
@@ -1179,7 +1196,7 @@ function applyTaskEventUnlocked(request, options = {}) {
     }
     if (!normalized.dryRun && reviewFinalizationIntent && completedArtifact) {
         try {
-            if (reviewFinalizationIntent.state === 'commit-started') {
+            if (reviewFinalizationIntent.state === 'consumption-started') {
                 const consumed = { ...reviewFinalizationIntent, state: 'consumed', updatedAt: Date.now() };
                 writeArtifactRecoveryIntent(resolved.repoRoot, consumed, { expected: reviewFinalizationIntent });
             }
@@ -1230,7 +1247,7 @@ function applyTaskEvent(request, options = {}) {
     const parts = eventParts(request.event);
     if (options.lockAlreadyHeld)
         return applyTaskEventUnlocked(request, options);
-    if (request.dryRun || parts.phase !== 'completed' || parts.family === 'manual-validation') {
+    if (request.dryRun || !['started', 'completed'].includes(parts.phase)) {
         return applyTaskEventUnlocked(request, options);
     }
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });

package/dist/lib/task/gate-policy.js

@@ -0,0 +1,94 @@
+const OPTIONAL_PLATFORM_AUDITS = new Set([
+    'closed-status-labels', 'status-label', 'comment-marker', 'pr-comment-marker',
+    'pr-comment-last-commit', 'pr-comment-content', 'comment-content', 'task-comment-content',
+    'in-labels-computed', 'pr-type-label', 'in-labels-match-pr', 'pr-assignee',
+    'requirements', 'issue-type', 'issue-fields', 'milestone'
+]);
+const STATUS_LABELS = {
+    'create-task': 'status: waiting-for-triage',
+    'analyze-task': 'status: pending-design-work',
+    'review-analysis': 'status: pending-design-work',
+    'plan-task': 'status: pending-design-work',
+    'review-plan': 'status: pending-design-work',
+    'code-task': 'status: in-progress',
+    'review-code': 'status: in-progress'
+};
+const ARTIFACT_COMMENT_SKILLS = new Set([
+    'analyze-task', 'plan-task', 'review-analysis', 'review-plan', 'code-task',
+    'review-code', 'review-pr', 'run-manual-validation'
+]);
+const PR_AUDIT_SKILLS = new Set(['create-pr']);
+const IN_LABEL_AUDIT_SKILLS = new Set(['code-task', 'commit', 'create-pr']);
+export function platformAuditPolicy(checkId, context) {
+    const skillName = context.skillName || '';
+    const artifactComment = Boolean(context.artifactFile) && ARTIFACT_COMMENT_SKILLS.has(skillName);
+    const prAudit = PR_AUDIT_SKILLS.has(skillName);
+    const inLabelAudit = IN_LABEL_AUDIT_SKILLS.has(skillName);
+    switch (checkId) {
+        case 'status-label':
+            return { classification: 'soft', enabled: Boolean(STATUS_LABELS[skillName]), expectedStatusLabel: STATUS_LABELS[skillName] };
+        case 'comment-marker':
+            return {
+                classification: 'soft',
+                enabled: artifactComment || skillName === 'complete-task',
+                ...(artifactComment ? { expectedCommentMarkerKey: 'artifact' } : skillName === 'complete-task' ? { expectedCommentMarkerKey: 'summary' } : {})
+            };
+        case 'pr-comment-marker':
+            return {
+                classification: 'soft',
+                enabled: skillName === 'commit' || prAudit,
+                ...(skillName === 'commit' || prAudit ? { expectedPrCommentMarkerKey: 'prSummary' } : {})
+            };
+        case 'pr-comment-last-commit':
+            return {
+                classification: 'soft',
+                enabled: skillName === 'commit',
+                ...(skillName === 'commit' ? { expectedPrCommentMarkerKey: 'prSummary' } : {})
+            };
+        case 'pr-comment-content':
+            return {
+                classification: 'soft',
+                enabled: skillName === 'complete-manual-validation',
+                ...(skillName === 'complete-manual-validation' ? { expectedPrCommentMarkerKey: 'prSummary' } : {})
+            };
+        case 'comment-content':
+            return { classification: 'soft', enabled: artifactComment, expectedCommentMarkerKey: 'artifact' };
+        case 'task-comment-content':
+            return { classification: 'soft', enabled: true };
+        case 'in-labels-computed':
+            return { classification: 'soft', enabled: inLabelAudit };
+        case 'pr-type-label':
+        case 'in-labels-match-pr':
+        case 'pr-assignee':
+            return { classification: 'soft', enabled: prAudit };
+        case 'requirements':
+            return { classification: 'soft', enabled: skillName === 'complete-task' };
+        case 'milestone':
+            return { classification: 'soft', enabled: true, requireSpecificMilestone: skillName === 'code-task' };
+        case 'closed-status-labels':
+        case 'issue-type':
+        case 'issue-fields':
+            return { classification: 'soft', enabled: true };
+    }
+}
+export function classificationForCheck(checkId) {
+    return checkId.startsWith('platform.') && OPTIONAL_PLATFORM_AUDITS.has(checkId.slice('platform.'.length))
+        ? 'soft'
+        : 'hard';
+}
+export function effectiveStatus(status, classification) {
+    return classification === 'hard' ? status : 'pass';
+}
+export function normalizeVerificationRecord(record) {
+    const checkId = record.checkId ?? record.type;
+    const classification = record.classification ?? classificationForCheck(checkId);
+    return {
+        ...record,
+        checkId,
+        classification,
+        effectiveStatus: record.effectiveStatus ?? effectiveStatus(record.status, classification),
+        reason: record.reason ?? record.fail_type ?? (classification === 'info' ? 'NOT_APPLICABLE' : record.status === 'pass' ? 'OK' : 'CHECK_FAILED'),
+        action: record.action ?? (classification === 'info' || record.status === 'pass' ? 'No action required' : 'Review the check evidence and retry after correction')
+    };
+}
+//# sourceMappingURL=gate-policy.js.map

package/dist/lib/task/intermediate-cleanup.js

@@ -292,12 +292,37 @@ function cleanupConsumedRecoveryFiles(repoRoot, task, candidate) {
         return false;
     }
     for (const entry of entries) {
-        if (entry.isSymbolicLink() || !entry.isFile() || !['baseline.md', 'candidate.md', 'final.md', 'publish.md'].includes(entry.name))
+        if (entry.isSymbolicLink())
+            return false;
+        if (entry.isFile()) {
+            if (!['baseline.md', 'candidate.md', 'final.md', 'publish.md'].includes(entry.name))
+                return false;
+            continue;
+        }
+        if (!entry.isDirectory() || entry.name !== 'generations')
+            return false;
+        let generations;
+        try {
+            generations = fs.readdirSync(path.join(recovery, entry.name), { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        if (generations.some((generation) => generation.isSymbolicLink()
+            || !generation.isFile() || !/^[a-f0-9]{64}\.md$/u.test(generation.name)))
             return false;
     }
     try {
-        for (const entry of entries)
-            fs.unlinkSync(path.join(recovery, entry.name));
+        for (const entry of entries) {
+            const target = path.join(recovery, entry.name);
+            if (entry.isFile())
+                fs.unlinkSync(target);
+            else {
+                for (const generation of fs.readdirSync(target, { withFileTypes: true }))
+                    fs.unlinkSync(path.join(target, generation.name));
+                fs.rmdirSync(target);
+            }
+        }
         fs.rmdirSync(recovery);
         const recoveryRoot = path.dirname(recovery);
         if (fs.readdirSync(recoveryRoot).length === 0)

package/dist/lib/task/local-artifact-finalization.js

@@ -2,13 +2,13 @@ import fs from 'node:fs';
 import { inspectDecisionDetailDuplicates } from './decision-details.js';
 import { scanVisibleMarkdown } from './markdown.js';
 import { parseArtifactName } from './artifact-name.js';
-import { hasOpenArtifactRound, parseCodePlanInputReference, validateArtifactPublication, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { hasOpenArtifactRound, validateArtifactPublication, validateCompletedArtifact } from './artifact-lifecycle.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.js';
 import { canonicalSemanticDigest, inspectArtifactPatterns, inspectArtifactStructure, sha256Content } from './artifact-operations.js';
 import { getArtifactSchema } from './artifact-schema.js';
 import { readArtifactRecoveryIntent } from './artifact-repair-intent.js';
-import { beginArtifactRecovery, commitArtifactRecovery, consumeArtifactRecovery, prepareArtifactRecoveryCommit, recordArtifactRecoveryPassed, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
+import { beginArtifactRecovery, commitArtifactRecovery, consumeArtifactRecovery, prepareArtifactRecoveryFinal, prepareArtifactRecoveryCommit, recordArtifactRecoveryPassed, reconcileArtifactRecovery, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
 import { consumeLifecycleRecoveryAttestation, lifecycleRecoveryAttestationDigest, validateLifecycleRecoveryAttestation } from './control-authority.js';
 const LOCAL_ARTIFACT_REQUIRED_SECTIONS = {
     analysis: getArtifactSchema('analysis').sections.map((section) => section.headings.zh),
@@ -97,13 +97,16 @@ function validateLocalArtifact(content, options) {
     if (!decisionDetails.ok)
         diagnostics.push({ code: 'LOCAL_DECISION_DETAIL_DUPLICATE', message: decisionDetails.message, line: null });
     if (options.taskContent !== undefined) {
-        const expected = expectedQualificationRelations(options.taskContent, options.family);
-        if (!expected.ok)
+        const identity = options.artifact ? parseArtifactName(options.artifact) : null;
+        const expected = identity?.family === options.family && hasOpenArtifactRound(options.taskContent, options.family, identity.round)
+            ? expectedQualificationRelations(options.taskContent, options.family)
+            : undefined;
+        if (expected && !expected.ok)
             diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${expected.code}: ${expected.message}`, line: null });
         const qualification = validateQualificationAudit(options.taskContent, content, {
             family: options.family,
             artifact: options.artifact,
-            expectedUpstreamRelations: expected.ok ? expected.relations : undefined
+            expectedUpstreamRelations: expected?.ok ? expected.relations : undefined
         });
         if (!qualification.ok)
             diagnostics.push({ code: 'LOCAL_QUALIFICATION_AUDIT_INVALID', message: `${qualification.code}: ${qualification.message}`, line: null });
@@ -136,7 +139,7 @@ function tupleFor(request, taskId, authority) {
         authorityDigest: authority ? authorityDigest(authority) : null
     };
 }
-function prepareLocalArtifact(request, candidate, authority) {
+function prepareLocalArtifact(request, candidate, authority, preflightOnly = false) {
     const failed = (code, message, extra = {}) => ({
         result: failedFinalization(request, { code, message }, extra), content: candidate ?? ''
     });
@@ -152,14 +155,16 @@ function prepareLocalArtifact(request, candidate, authority) {
     let taskContent;
     let content;
     let recovery;
+    let recoveryState;
     try {
         taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
         if (request.recoveryId) {
             const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
             if (!intent || intent.recoveryOperationId !== request.recoveryId)
                 return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'recovery id does not match the artifact journal');
-            if (!['awaiting-recovery', 'finalize-ready', 'commit-started'].includes(intent.state))
+            if (!['awaiting-preflight-recovery', 'preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready', 'commit-started'].includes(intent.state))
                 return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `recovery journal is in '${intent.state}' state`);
+            recoveryState = intent.state;
             recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
             content = fs.existsSync(recovery.stagingPath)
                 ? fs.readFileSync(recovery.stagingPath, 'utf8')
@@ -192,24 +197,63 @@ function prepareLocalArtifact(request, candidate, authority) {
     if (request.recoveryId) {
         if (!validation.ok)
             return { result, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+        if (preflightOnly && recovery && recoveryState === 'awaiting-preflight-recovery') {
+            const staged = stageArtifactCandidate(recovery, Buffer.from(content, 'utf8'), { lockAlreadyHeld: request.lockAlreadyHeld });
+            prepareArtifactRecoveryCommit(recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: request.lockAlreadyHeld });
+        }
         return {
-            result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(recovery) },
+            result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(recovery) },
             content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld
         };
     }
     const existing = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
     if (existing?.state === 'passed' || existing?.state === 'consumed') {
-        if (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest) {
+        if (existing.state === 'consumed' && (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest)) {
             return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'formal artifact does not match its completed recovery journal'), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
         }
+        if (existing.finalArtifactSha256 === artifactSha256 && existing.finalSemanticDigest === validation.semanticDigest) {
+            const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+            return {
+                result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) },
+                content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
+            };
+        }
+    }
+    if (existing && ['preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready'].includes(existing.state)) {
+        const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+        return {
+            result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) },
+            content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
+        };
+    }
+    if (existing?.state === 'commit-started') {
+        if (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest) {
+            return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'formal artifact does not match the interrupted recovery journal'), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+        }
         const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+        const reconciled = reconcileArtifactRecovery(context, {
+            lockAlreadyHeld: request.lockAlreadyHeld,
+            validateFinal: () => validation.semanticDigest === existing.finalSemanticDigest
+        });
+        if (reconciled.status !== 'passed') {
+            return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `interrupted recovery could not be reconciled: ${reconciled.status}`), content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+        }
         return {
-            result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) },
+            result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) },
             content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
         };
     }
     try {
         if (validation.ok) {
+            if (preflightOnly) {
+                const context = beginArtifactRecovery(tupleFor(request, resolved.taskId, authority), Buffer.from(content, 'utf8'), {
+                    repoRoot: resolved.repoRoot, taskDir: resolved.taskDir,
+                    ...(authority ? { recoveryId: authority.operationId } : {}), lockAlreadyHeld: request.lockAlreadyHeld
+                });
+                const staged = stageArtifactCandidate(context, Buffer.from(content, 'utf8'), { lockAlreadyHeld: request.lockAlreadyHeld });
+                prepareArtifactRecoveryCommit(context, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: request.lockAlreadyHeld });
+                return { result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+            }
             const context = recordArtifactRecoveryPassed(tupleFor(request, resolved.taskId, authority), {
                 repoRoot: resolved.repoRoot,
                 taskDir: resolved.taskDir,
@@ -219,7 +263,7 @@ function prepareLocalArtifact(request, candidate, authority) {
                 lockAlreadyHeld: request.lockAlreadyHeld
             });
             recovery = context;
-            return { result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+            return { result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
         }
         const context = beginArtifactRecovery(tupleFor(request, resolved.taskId, authority), Buffer.from(content, 'utf8'), {
             repoRoot: resolved.repoRoot,
@@ -237,7 +281,7 @@ function prepareLocalArtifact(request, candidate, authority) {
         return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', String(error)), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
     }
 }
-function commitLocalArtifactProvenance(prepared) {
+function commitLocalArtifactProvenance(prepared, options = {}) {
     if (!prepared.recovery || !prepared.repoRoot || prepared.result.status === 'failed' && !prepared.result.recovery)
         return prepared.result;
     if (prepared.result.status === 'failed')
@@ -250,30 +294,48 @@ function commitLocalArtifactProvenance(prepared) {
         if (intent.state === 'passed' || intent.state === 'consumed') {
             return {
                 ...prepared.result,
+                changed: false,
                 artifactSha256: intent.finalArtifactSha256,
                 semanticDigest: intent.finalSemanticDigest,
                 error: null
             };
         }
-        else if (intent.state === 'finalize-ready' || intent.state === 'commit-started') {
-            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+        else if (intent.state === 'commit-started') {
+            const reconciled = reconcileArtifactRecovery(prepared.recovery, {
+                lockAlreadyHeld: prepared.lockAlreadyHeld,
+                afterPublish: options.afterPublish
+            });
+            committed = reconciled.intent;
         }
-        else {
+        else if (intent.state === 'awaiting-preflight-recovery') {
             const staged = stageArtifactCandidate(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
             prepareArtifactRecoveryCommit(prepared.recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: prepared.lockAlreadyHeld });
             committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
         }
-        if (committed.state !== 'passed')
-            throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed.state}'`);
+        if (intent.state === 'preflight-ready' || intent.state === 'preflight-commit-started') {
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+        }
+        if (committed?.state === 'preflight-passed' || intent.state === 'preflight-passed') {
+            prepareArtifactRecoveryFinal(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        }
+        else if (intent.state === 'full-finalizer-ready') {
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        }
+        if (!committed || committed.state !== 'passed')
+            throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed?.state ?? intent.state}'`);
         return {
             ...prepared.result,
             status: 'passed',
+            changed: false,
             artifactSha256: committed.finalArtifactSha256,
             semanticDigest: committed.finalSemanticDigest,
             error: null
         };
     }
     catch (error) {
+        if (error instanceof Error && error.message.startsWith('TASK_WORKFLOW_FAULT_INJECTED:'))
+            throw error;
         return { ...prepared.result, status: 'failed', error: {
                 code: 'LOCAL_RECOVERY_COMMIT_FAILED', message: String(error)
             } };
@@ -295,5 +357,10 @@ function finalizeLocalArtifact(request, authority, options = {}) {
     }
     return result;
 }
-export { LOCAL_ARTIFACT_REQUIRED_SECTIONS, consumeLocalArtifactFinalizationIntent, finalizeLocalArtifact, prepareLocalArtifact, commitLocalArtifactProvenance, readArtifactRecoveryIntent as readLocalArtifactFinalizationIntent, canonicalSemanticDigest as semanticDigest, sha256Content, validateLocalArtifact };
+/** Validate and seal an immutable preflight generation without publishing the formal artifact. */
+function preflightLocalArtifact(request, authority) {
+    const prepared = prepareLocalArtifact(request, undefined, authority, true);
+    return prepared.result;
+}
+export { LOCAL_ARTIFACT_REQUIRED_SECTIONS, consumeLocalArtifactFinalizationIntent, finalizeLocalArtifact, preflightLocalArtifact, prepareLocalArtifact, commitLocalArtifactProvenance, readArtifactRecoveryIntent as readLocalArtifactFinalizationIntent, canonicalSemanticDigest as semanticDigest, sha256Content, validateLocalArtifact };
 //# sourceMappingURL=local-artifact-finalization.js.map