@fitlab-ai/agent-infra 0.10.0 → 0.11.1

package/dist/lib/task/orchestration.js

@@ -20,7 +20,7 @@ import { extractReviewBaseline, extractReviewDiffBase, extractReviewTargetHead,
 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';
+import { reconcileTaskInvalidation } from './invalidation-command.js';
 import { normalizeAgentToken } from '../agent-clients/tokens.js';
 function supportsLifecycleDelegation(client) {
     return getAgentClientCapability(client, 'subagents').level !== 'unsupported'
@@ -511,14 +511,12 @@ 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 {
@@ -528,9 +526,6 @@ function routeOrchestration(taskRef, options = {}) {
             return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(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, options);
@@ -545,6 +540,9 @@ function routeOrchestration(taskRef, options = {}) {
     if (!routed)
         return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
     if ('completion' in routed) {
+        if (facts.facts.executionBusy && !run?.pendingDelegation) {
+            return failed('ORCHESTRATION_EXECUTION_BUSY', 'clean completion requires no open lifecycle execution', resolved.taskId);
+        }
         const reviewRound = maxArtifactRound(fs.readdirSync(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) {
@@ -670,6 +668,10 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
     }
     if (run.stepCount >= run.maxSteps)
         return pauseOrchestration(taskRef, 'ORCHESTRATION_MAX_STEPS', 'maximum orchestration steps reached', true, options);
+    const invalidation = reconcileTaskInvalidation(taskRef, { repoRoot: resolved.repoRoot });
+    if (invalidation.status === 'failed') {
+        return failed('ORCHESTRATION_INVALIDATION_RECONCILE_FAILED', `${invalidation.error?.code ?? 'UNKNOWN'}: ${invalidation.error?.message ?? ''}`, resolved.taskId);
+    }
     const routed = routeOrchestration(taskRef, options);
     if (!routed.next)
         return routed;

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

@@ -118,20 +118,26 @@ function parseReviewSummary(content) {
 function equalCounts(left, right) {
     return left.blocker === right.blocker && left.major === right.major && left.minor === right.minor;
 }
-function finalizeReviewSummaryContent(content, counts) {
+function finalizeReviewSummaryContent(content, counts, options = {}) {
     const parsed = parseReviewSummary(content);
     if (!parsed.ok)
         return parsed;
     if (parsed.summary.countState === 'numeric') {
         if (equalCounts(parsed.summary.counts, counts))
             return { ok: true, changed: false, content };
-        return {
-            ok: false,
-            code: 'REVIEW_SUMMARY_COUNT_MISMATCH',
-            message: 'review summary finding counts do not match the ledger snapshot'
-        };
+        if (!options.refreshNumericCounts)
+            return {
+                ok: false,
+                code: 'REVIEW_SUMMARY_COUNT_MISMATCH',
+                message: 'review summary finding counts do not match the ledger snapshot'
+            };
     }
     let line = content.slice(parsed.findingsStart, parsed.findingsEnd);
+    if (parsed.summary.countState === 'numeric') {
+        const values = [counts.blocker, counts.major, counts.minor];
+        let ordinal = 0;
+        line = line.replace(/\d+(?=\s*(?:阻塞项|主要|次要|blockers?\b|majors?\b|minors?\b))/gi, () => String(values[ordinal++]));
+    }
     line = line
         .replace(PLACEHOLDERS[0], String(counts.blocker))
         .replace(PLACEHOLDERS[1], String(counts.major))

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

@@ -1,6 +1,6 @@
 export function parseReviewCommand(args) {
-    if (!args[0] || args[1] !== 'finalize-summary')
-        throw new Error('task ref and finalize-summary are required');
+    if (!args[0] || !['preflight', 'finalize-summary'].includes(args[1] ?? ''))
+        throw new Error('task ref and a supported review operation are required');
     const values = {};
     const flags = {
         '--stage': 'stage', '--artifact': 'artifact', '--orchestrated': 'orchestrated', '--dry-run': 'dryRun',

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

@@ -10,8 +10,9 @@ import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-
 import { allowsManualOverride } from './guard-override.js';
 import { getArtifactSchema } from './artifact-schema.js';
 import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.js';
+import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.js';
 import { readArtifactRecoveryIntent } from './artifact-repair-intent.js';
-import { beginArtifactRecovery, commitArtifactRecovery, prepareArtifactRecoveryCommit, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
+import { beginArtifactRecovery, commitArtifactRecovery, prepareArtifactRecoveryFinal, prepareArtifactRecoveryCommit, reconcileArtifactRecovery, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
 const STAGES = {
     analysis: { family: 'review-analysis' },
     plan: { family: 'review-plan' },
@@ -37,6 +38,154 @@ function failed(request, code, message, taskId = null, stageStatus = null, extra
         ...extra
     };
 }
+function preflightFailed(request, code, message, taskId = null, extra = {}) {
+    const { status: _status, intent: _intent, stageStatus: _stageStatus, ...finalizationExtra } = extra;
+    return {
+        ...failed(request, code, message, taskId, null, finalizationExtra),
+        status: 'failed',
+        intent: 'preflight',
+        stageStatus: null
+    };
+}
+/** Validate and seal a review draft before any finding-ledger write. */
+function preflightReviewSummaryUnlocked(request, options = {}) {
+    const stage = request.stage;
+    const spec = STAGES[stage];
+    if (!spec)
+        return preflightFailed(request, 'REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
+    if (!request.taskRef || !request.artifact)
+        return preflightFailed(request, 'REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return preflightFailed(request, resolved.code, resolved.message, resolved.taskId ?? null);
+    if (resolved.state !== 'active')
+        return preflightFailed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+    const parsed = parseArtifactName(request.artifact);
+    if (!parsed || parsed.family !== spec.family)
+        return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${spec.family}`, resolved.taskId);
+    const publicationError = validateArtifactPublication(resolved.taskDir, spec.family, request.artifact);
+    if (publicationError)
+        return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', publicationError.message, resolved.taskId);
+    let taskContent;
+    let content;
+    let recovery;
+    try {
+        taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+        if (request.recoveryId) {
+            const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
+            if (!intent || intent.recoveryOperationId !== request.recoveryId)
+                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal', resolved.taskId);
+            if (!['awaiting-preflight-recovery', 'preflight-ready'].includes(intent.state))
+                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`, resolved.taskId);
+            recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
+            content = fs.existsSync(recovery.stagingPath)
+                ? fs.readFileSync(recovery.stagingPath, 'utf8')
+                : fs.readFileSync(recovery.formalPath, 'utf8');
+        }
+        else {
+            const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
+            if (!validated.ok)
+                return preflightFailed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
+            content = fs.readFileSync(validated.artifact.path, 'utf8');
+            const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
+            if (intent?.state === 'preflight-ready')
+                recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
+            if (intent?.state === 'consumed')
+                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'review artifact was already finalized', resolved.taskId);
+        }
+    }
+    catch (error) {
+        return preflightFailed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
+    }
+    if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round))
+        return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`, resolved.taskId);
+    const execution = validateLifecycleExecution(request.taskRef, {
+        mode: request.orchestrated ? 'orchestrated' : 'standalone',
+        identity: { stage: spec.family, round: parsed.round, artifact: request.artifact, role: 'reviewer' },
+        dryRun: request.dryRun
+    }, { repoRoot: options.repoRoot });
+    if (!execution.ok)
+        return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`, resolved.taskId);
+    const artifactSha256 = sha256Content(content);
+    const semanticDigest = canonicalSemanticDigest(content);
+    const detail = inspectDecisionDetailDuplicates(content);
+    const structure = inspectArtifactContract(content, getArtifactSchema(spec.family));
+    const expected = expectedQualificationRelations(taskContent, spec.family);
+    if (!expected.ok)
+        return preflightFailed(request, 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', `${expected.code}: ${expected.message}`, resolved.taskId, { artifactSha256, semanticDigest });
+    const qualification = validateQualificationAudit(taskContent, content, {
+        family: spec.family,
+        artifact: request.artifact,
+        expectedUpstreamRelations: expected.relations
+    });
+    const qualificationError = qualification.ok ? null : qualification;
+    if (!detail.ok || !structure.ok || qualificationError) {
+        if (!recovery && !request.dryRun) {
+            try {
+                recovery = beginArtifactRecovery({
+                    taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
+                    requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
+                }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
+            }
+            catch (error) {
+                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId);
+            }
+        }
+        const diagnostics = [
+            ...(!detail.ok ? [`${detail.code}: ${detail.message}`] : []),
+            ...structure.diagnostics.map((item) => `${item.code}: ${item.message}`),
+            ...(qualificationError ? [`${qualificationError.code}: ${qualificationError.message}`] : [])
+        ].join('; ');
+        return preflightFailed(request, !detail.ok ? 'REVIEW_DECISION_DETAIL_INVALID' : !structure.ok ? 'REVIEW_ARTIFACT_STRUCTURE_INVALID' : 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', diagnostics, resolved.taskId, {
+            artifactSha256, semanticDigest,
+            ...(recovery ? { recovery: recoveryInfo(recovery) } : {})
+        });
+    }
+    if (request.dryRun || recovery && readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact)?.state === 'preflight-ready') {
+        return {
+            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, ...(recovery ? { recovery: recoveryInfo(recovery) } : {}) }),
+            status: 'passed', changed: false, error: null
+        };
+    }
+    try {
+        recovery ??= beginArtifactRecovery({
+            taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
+            requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
+        }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
+        const staged = stageArtifactCandidate(recovery, Buffer.from(content, 'utf8'), { lockAlreadyHeld: options.lockAlreadyHeld });
+        prepareArtifactRecoveryCommit(recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: options.lockAlreadyHeld });
+        return {
+            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, recovery: recoveryInfo(recovery) }),
+            status: 'passed', changed: false, error: null
+        };
+    }
+    catch (error) {
+        return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId, { artifactSha256, semanticDigest });
+    }
+}
+function preflightReviewSummary(request, options = {}) {
+    if (request.dryRun || options.lockAlreadyHeld)
+        return preflightReviewSummaryUnlocked(request, options);
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return preflightReviewSummaryUnlocked(request, options);
+    try {
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.preflight', () => preflightReviewSummaryUnlocked(request, { ...options, lockAlreadyHeld: true }));
+    }
+    catch (error) {
+        if (!(error instanceof TaskExecutionLockError))
+            throw error;
+        return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
+    }
+}
+function recoveryInfo(recovery) {
+    return {
+        recoveryId: recovery.recoveryId,
+        candidatePath: recovery.stagingPath,
+        baselineSha256: recovery.baselineSha256,
+        baselineSemanticDigest: recovery.baselineSemanticDigest
+    };
+}
 /** Prepare domain validation, summary bytes and provenance before any publication. */
 function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     let taskId = null;
@@ -76,7 +225,7 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
             const intent = readArtifactRecoveryIntent(resolved.repoRoot, taskId, spec.family, request.artifact);
             if (!intent || intent.recoveryOperationId !== request.recoveryId)
                 return reject('REVIEW_PROVENANCE_INVALID', '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 reject('REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`);
             recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
             artifactContent = fs.existsSync(recovery.stagingPath)
@@ -97,11 +246,15 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     catch (error) {
         return reject('REVIEW_PROVENANCE_INVALID', String(error), digests);
     }
-    if (repairIntent?.state === 'passed' || repairIntent?.state === 'consumed') {
+    if (repairIntent?.state === 'consumed') {
         if (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest) {
             return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', digests);
         }
     }
+    if (repairIntent?.state === 'passed'
+        && (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest)) {
+        repairIntent = undefined;
+    }
     if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) {
         return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`);
     }
@@ -155,10 +308,18 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
             ...(recovery ? { recovery } : {})
         };
     }
-    const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
+    const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts, {
+        refreshNumericCounts: Boolean(request.recoveryId && recovery)
+    });
     if (!transformed.ok)
         return reject(transformed.code, transformed.message);
     const finalDigests = { artifactSha256: sha256Content(transformed.content), semanticDigest: canonicalSemanticDigest(transformed.content) };
+    if (!recovery && repairIntent?.state === 'commit-started') {
+        if (repairIntent.finalArtifactSha256 !== finalDigests.artifactSha256 || repairIntent.finalSemanticDigest !== finalDigests.semanticDigest) {
+            return reject('REVIEW_PROVENANCE_INVALID', 'formal review artifact does not match the interrupted recovery journal', finalDigests);
+        }
+        recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, repairIntent);
+    }
     if (!recovery && (repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')) {
         if (transformed.changed)
             return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact requires changes after its completed recovery was consumed', finalDigests);
@@ -197,7 +358,7 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
         lockAlreadyHeld: options.lockAlreadyHeld
     };
 }
-function commitReviewSummaryProvenance(prepared, repoRoot) {
+function commitReviewSummaryProvenance(prepared, repoRoot, options = {}) {
     if (prepared.result.status === 'failed' || !prepared.recovery)
         return prepared.result;
     try {
@@ -205,16 +366,40 @@ function commitReviewSummaryProvenance(prepared, repoRoot) {
         if (!intent)
             throw new Error('ARTIFACT_RECOVERY_INTENT_MISSING');
         let committed;
-        if (intent.state === 'finalize-ready' || intent.state === 'commit-started') {
-            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+        if (intent.state === 'passed' || intent.state === 'consumed') {
+            return {
+                ...prepared.result,
+                status: 'no-op',
+                changed: false,
+                artifactSha256: intent.finalArtifactSha256,
+                semanticDigest: intent.finalSemanticDigest,
+                error: null
+            };
         }
-        else {
+        else if (intent.state === 'commit-started') {
+            const reconciled = reconcileArtifactRecovery(prepared.recovery, {
+                lockAlreadyHeld: prepared.lockAlreadyHeld,
+                afterPublish: options.afterPublish
+            });
+            committed = reconciled.intent;
+        }
+        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}'`);
+        else 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,
             artifactSha256: committed.finalArtifactSha256,
@@ -223,6 +408,8 @@ function commitReviewSummaryProvenance(prepared, repoRoot) {
         };
     }
     catch (error) {
+        if (error instanceof Error && error.message.startsWith('TASK_WORKFLOW_FAULT_INJECTED:'))
+            throw error;
         return { ...prepared.result, status: 'failed', error: {
                 code: 'REVIEW_RECOVERY_COMMIT_FAILED', message: `cannot publish review candidate: ${String(error)}`
             } };
@@ -268,5 +455,5 @@ function finalizeReviewSummary(request, options = {}) {
         return failed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
     }
 }
-export { finalizeReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
+export { finalizeReviewSummary, preflightReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 //# sourceMappingURL=review-finalization.js.map

package/dist/lib/{host-control → task}/secure-fs.js

@@ -1,6 +1,6 @@
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createHash } from 'node:crypto';
 const NO_FOLLOW = fs.constants.O_NOFOLLOW ?? 0;
 const DIRECTORY = fs.constants.O_DIRECTORY ?? 0;
 export class SecureFileError extends Error {
@@ -15,11 +15,8 @@ function conflict(message) {
     throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', message);
 }
 function sameStat(left, right) {
-    return left.dev === right.dev
-        && left.ino === right.ino
-        && left.size === right.size
-        && left.mtimeNs === right.mtimeNs
-        && left.ctimeNs === right.ctimeNs;
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size
+        && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
 }
 function assertNoSymlinkAncestors(candidate) {
     let current = path.dirname(candidate);
@@ -36,15 +33,12 @@ function assertNoSymlinkAncestors(candidate) {
 export async function readStableFile(candidate, options) {
     return readStableFileSync(candidate, options);
 }
-/** Shared bounded reader for synchronous domain commands and async workflow callers. */
 export function readStableFileSync(candidate, options) {
-    if (!path.isAbsolute(candidate)) {
+    if (!path.isAbsolute(candidate))
         conflict('candidate path must be absolute and terminal');
-    }
     assertNoSymlinkAncestors(candidate);
     let descriptor;
     try {
-        // O_NONBLOCK lets fstat reject a FIFO even when it has no writer.
         descriptor = fs.openSync(candidate, fs.constants.O_RDONLY | NO_FOLLOW | (fs.constants.O_NONBLOCK ?? 0));
         const before = fs.fstatSync(descriptor, { bigint: true });
         if (!before.isFile())
@@ -63,18 +57,16 @@ export function readStableFileSync(candidate, options) {
         if (!sameStat(before, after))
             conflict('candidate identity or metadata changed during read');
         const sha256 = createHash('sha256').update(bytes).digest('hex');
-        if (options.expectedSha256 !== undefined && sha256 !== options.expectedSha256) {
+        if (options.expectedSha256 !== undefined && sha256 !== options.expectedSha256)
             conflict('candidate digest does not match the expected digest');
-        }
         return { bytes, sha256, stat: after };
     }
     catch (error) {
         if (error instanceof SecureFileError)
             throw error;
         const code = error.code;
-        if (code === 'ELOOP' || code === 'ENOTSUP' || code === 'EINVAL') {
+        if (code === 'ELOOP' || code === 'ENOTSUP' || code === 'EINVAL')
             conflict('candidate terminal is not a stable non-symlink file');
-        }
         throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', error instanceof Error ? error.message : String(error));
     }
     finally {
@@ -93,9 +85,8 @@ export async function writeAtomicFile(target, bytes, mode = 0o600, expectedSha25
         catch {
             throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is missing');
         }
-        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        if (!stat.isDirectory() || stat.isSymbolicLink())
             throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is not a real directory');
-        }
         const next = path.dirname(current);
         if (next === current)
             break;
@@ -103,9 +94,8 @@ export async function writeAtomicFile(target, bytes, mode = 0o600, expectedSha25
     }
     try {
         const existing = await fs.promises.lstat(target);
-        if (existing.isSymbolicLink() || !existing.isFile()) {
+        if (existing.isSymbolicLink() || !existing.isFile())
             throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative target is not a regular file');
-        }
     }
     catch (error) {
         if (error.code !== 'ENOENT')
@@ -120,7 +110,6 @@ export async function writeAtomicFile(target, bytes, mode = 0o600, expectedSha25
         await handle.chmod(mode);
         await handle.close();
         handle = undefined;
-        // Check after all asynchronous preparation; keep the final check/rename adjacent.
         if (expectedSha256 !== undefined)
             readStableFileSync(target, { maxBytes: 1024 * 1024, expectedSha256 });
         fs.renameSync(temporary, target);

package/dist/lib/task/verification-engine.js

@@ -29,6 +29,7 @@ import { validateLocalArtifact } from "./local-artifact-finalization.js";
 import { validateQualificationAudit } from "./qualification-audit.js";
 import { getArtifactSchema } from "./artifact-schema.js";
 import { inspectArtifactContract } from "./artifact-operations.js";
+import { normalizeVerificationRecord } from './gate-policy.js';
 import { manualValidationFinalSummaryProjectionMatches } from "./manual-validation-receipt.js";
 import { readManualValidationCompletion } from "./manual-validation-completion.js";
 import { sha256File } from "./artifact-receipts.js";
@@ -1198,19 +1199,19 @@ function interpolate(template, taskDir, artifactFile) {
         .replace(/\{artifact-stem\}/g, artifactStem);
 }
 function summarizeGate(checks) {
-    if (checks.some((check) => check.status === "blocked")) {
+    if (checks.some((check) => check.effectiveStatus === "blocked")) {
         return "blocked";
     }
-    if (checks.some((check) => check.status === "fail")) {
+    if (checks.some((check) => check.effectiveStatus === "fail")) {
         return "fail";
     }
     return "pass";
 }
 function summarizeChecks(checks) {
     const counts = {
-        pass: checks.filter((check) => check.status === "pass").length,
-        fail: checks.filter((check) => check.status === "fail").length,
-        blocked: checks.filter((check) => check.status === "blocked").length
+        pass: checks.filter((check) => check.effectiveStatus === "pass").length,
+        fail: checks.filter((check) => check.effectiveStatus === "fail").length,
+        blocked: checks.filter((check) => check.effectiveStatus === "blocked").length
     };
     if (counts.blocked > 0) {
         return `${counts.pass} passed, ${counts.fail} failed, ${counts.blocked} blocked`;
@@ -1221,7 +1222,7 @@ function buildAction(gate, checks) {
     if (gate === "pass") {
         return "All declared checks passed";
     }
-    const firstFailure = checks.find((check) => check.status !== "pass");
+    const firstFailure = checks.find((check) => check.effectiveStatus !== "pass");
     if (!firstFailure) {
         return "Review validation output";
     }
@@ -1277,16 +1278,16 @@ async function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks:
         for (const [type, checkConfig] of Object.entries(verifyConfig.checks || {})) {
             if (checkConfig === null)
                 continue;
-            const result = await runCheck(type, {
+            const result = normalizeVerificationRecord(await runCheck(type, {
                 mode,
                 skillName,
                 taskDir: path.resolve(taskDir),
                 artifactFile,
                 repositoryRoot: repoRoot,
                 config: checkConfig
-            }, shared);
-            checks.push(result);
-            if (result.status === "blocked")
+            }, shared));
+            checks.push(...(result.subchecks?.map(normalizeVerificationRecord) ?? [result]));
+            if (checks.at(-1)?.effectiveStatus === "blocked")
                 break;
         }
         const gate = summarizeGate(checks);
@@ -1298,15 +1299,25 @@ async function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks:
         return { skill: skillName, ...failResult(type, `Unknown check type '${type}' for skill '${skillName}'.`) };
     if (config === null)
         return { skill: skillName, ...passResult(type, `Check '${type}' is disabled for skill '${skillName}'.`) };
+    const result = normalizeVerificationRecord(await runCheck(type, {
+        skillName,
+        taskDir: path.resolve(taskDir),
+        artifactFile,
+        repositoryRoot: repoRoot,
+        config
+    }, shared));
+    if (!result.subchecks?.length)
+        return { skill: skillName, ...result };
+    const checks = result.subchecks.map(normalizeVerificationRecord);
+    const gate = summarizeGate(checks);
     return {
         skill: skillName,
-        ...await runCheck(type, {
-            skillName,
-            taskDir: path.resolve(taskDir),
-            artifactFile,
-            repositoryRoot: repoRoot,
-            config
-        }, shared)
+        ...result,
+        status: gate,
+        effectiveStatus: gate,
+        reason: gate === 'pass' ? 'OK' : checks.find((check) => check.effectiveStatus !== 'pass')?.reason ?? 'CHECK_FAILED',
+        action: buildAction(gate, checks),
+        checks
     };
 }
 export { verifyInProcess };

package/dist/lib/task/verification.js

@@ -80,7 +80,7 @@ async function verifyTaskEvent(request, options = {}) {
     else {
         for (const check of spec.checks ?? []) {
             const payload = await engine({ mode: 'checks', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [check], repositoryRoot: resolved.repoRoot });
-            const status = payload.status;
+            const status = (payload.effectiveStatus ?? payload.status);
             if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
                 invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, status: 'pass', humanOverride: 'human-approved', originalStatus: status } });
                 break;
@@ -103,19 +103,35 @@ function statusLabel(status) {
 function renderPayload(payload) {
     const lines = [];
     if (Array.isArray(payload.checks)) {
-        lines.push(`Verification: ${payload.gate} | Skill: ${payload.skill}`, '');
+        const gateMode = typeof payload.gate === 'string';
+        lines.push(gateMode
+            ? `Verification: ${payload.gate} | Skill: ${payload.skill}`
+            : `Check: ${payload.status} | Skill: ${payload.skill} | Type: ${payload.type}`, '');
         for (const check of payload.checks) {
-            lines.push(`  [${statusLabel(check.status)}] ${check.type} - ${check.message}`);
+            const raw = statusLabel(check.status);
+            const effective = statusLabel(check.effectiveStatus ?? check.status);
+            const reason = check.reason ?? 'CHECK_FAILED';
+            const message = check.message ?? reason;
+            lines.push(`  [${effective}] ${check.checkId ?? check.type} (${check.classification ?? 'hard'}; raw ${raw}; reason ${reason}) - ${message}; ${check.action ?? 'Review validation output'}`);
         }
-        lines.push('', `Result: ${payload.summary} - ${payload.action}`);
+        const summary = payload.summary ?? (() => {
+            const checks = payload.checks;
+            const statuses = checks.map((check) => check.effectiveStatus ?? check.status);
+            return `${statuses.filter((status) => status === 'pass').length} passed, ${statuses.filter((status) => status === 'fail').length} failed${statuses.includes('blocked') ? `, ${statuses.filter((status) => status === 'blocked').length} blocked` : ''}`;
+        })();
+        lines.push('', `Result: ${summary} - ${payload.action}`);
     }
     else {
         lines.push(`Check: ${payload.status} | Skill: ${payload.skill} | Type: ${payload.type}`, '');
-        lines.push(`  [${statusLabel(payload.status)}] ${payload.type} - ${payload.message}`);
-        const summary = payload.status === 'pass' ? '1 passed, 0 failed'
-            : payload.status === 'blocked' ? '0 passed, 0 failed, 1 blocked' : '0 passed, 1 failed';
-        const action = payload.status === 'pass' ? 'Requested check passed'
-            : payload.status === 'blocked' ? `Resolve blocked ${payload.type} check and re-run check`
+        const raw = statusLabel(payload.status);
+        const effective = statusLabel(payload.effectiveStatus ?? payload.status);
+        const reason = payload.reason ?? 'CHECK_FAILED';
+        lines.push(`  [${effective}] ${payload.checkId ?? payload.type} (${payload.classification ?? 'hard'}; raw ${raw}; reason ${reason}) - ${payload.message ?? reason}; ${payload.action ?? 'Review validation output'}`);
+        const status = payload.effectiveStatus ?? payload.status;
+        const summary = status === 'pass' ? '1 passed, 0 failed'
+            : status === 'blocked' ? '0 passed, 0 failed, 1 blocked' : '0 passed, 1 failed';
+        const action = status === 'pass' ? 'Requested check passed'
+            : status === 'blocked' ? `Resolve blocked ${payload.type} check and re-run check`
                 : `Fix ${payload.type} issues and re-run check`;
         lines.push('', `Result: ${summary} - ${action}`);
     }

package/dist/lib/task/workflow-command.js

@@ -1,7 +1,9 @@
 export const TASK_WORKFLOW_COMMANDS = Object.freeze({
     'artifact-inspect': ['task-artifact', 'inspect'],
     'artifact-init': ['task-artifact', 'init'],
+    'artifact-preflight': ['task-artifact', 'preflight'],
     'artifact-finalize-local': ['task-artifact', 'finalize-local'],
+    'review-preflight': ['task-review', 'preflight'],
     'review-finalize-summary': ['task-review', 'finalize-summary'],
     event: ['task-event', null],
     'ledger-finding-response': ['task-ledger', 'finding-respond'],