@fitlab-ai/agent-infra 0.11.0 → 0.11.2

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

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { parseArtifactName } from './artifact-name.js';
-import { validateCompletedArtifact, hasOpenArtifactRound, validateArtifactPublication } from './artifact-lifecycle.js';
+import { validateCompletedArtifact, validateArtifactPublication } from './artifact-lifecycle.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { finalizeReviewSummaryContent } from './review-artifacts.js';
 import { inspectDecisionDetailDuplicates } from './decision-details.js';
@@ -11,8 +13,6 @@ 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, prepareArtifactRecoveryFinal, prepareArtifactRecoveryCommit, reconcileArtifactRecovery, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
 const STAGES = {
     analysis: { family: 'review-analysis' },
     plan: { family: 'review-plan' },
@@ -47,7 +47,7 @@ function preflightFailed(request, code, message, taskId = null, extra = {}) {
         stageStatus: null
     };
 }
-/** Validate and seal a review draft before any finding-ledger write. */
+/** Validate the current review draft before any finding-ledger write. */
 function preflightReviewSummaryUnlocked(request, options = {}) {
     const stage = request.stage;
     const spec = STAGES[stage];
@@ -68,39 +68,16 @@ function preflightReviewSummaryUnlocked(request, options = {}) {
         return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', publicationError.message, resolved.taskId);
     let taskContent;
     let content;
-    let recovery;
-    let existingIntent;
     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);
-            existingIntent = intent;
-            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);
-        }
+        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');
     }
     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' },
@@ -122,17 +99,6 @@ function preflightReviewSummaryUnlocked(request, options = {}) {
     });
     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}`),
@@ -140,36 +106,18 @@ function preflightReviewSummaryUnlocked(request, options = {}) {
         ].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 (!recovery && existingIntent?.state === 'passed') {
+    if (request.dryRun) {
         return {
             ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest }),
             status: 'passed', changed: false, error: null
         };
     }
-    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 });
-    }
+    return {
+        ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest }),
+        status: 'passed', changed: false, error: null
+    };
 }
 function preflightReviewSummary(request, options = {}) {
     if (request.dryRun || options.lockAlreadyHeld)
@@ -186,14 +134,6 @@ function preflightReviewSummary(request, options = {}) {
         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;
@@ -227,45 +167,9 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     catch (error) {
         return reject('REVIEW_ARTIFACT_NOT_REGULAR', String(error));
     }
-    let recovery;
-    if (request.recoveryId) {
-        try {
-            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-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)
-                ? fs.readFileSync(recovery.stagingPath, 'utf8')
-                : fs.readFileSync(recovery.formalPath, 'utf8');
-        }
-        catch (error) {
-            return reject('REVIEW_PROVENANCE_INVALID', String(error));
-        }
-    }
     const artifactSha256 = sha256Content(artifactContent);
     const semanticDigest = canonicalSemanticDigest(artifactContent);
     const digests = { artifactSha256, semanticDigest };
-    let repairIntent;
-    try {
-        repairIntent = readArtifactRecoveryIntent(resolved.repoRoot, taskId, spec.family, request.artifact);
-    }
-    catch (error) {
-        return reject('REVIEW_PROVENANCE_INVALID', String(error), digests);
-    }
-    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`);
-    }
     const execution = validateLifecycleExecution(request.taskRef, {
         mode: request.orchestrated ? 'orchestrated' : 'standalone',
         identity: { stage: spec.family, round: parsed.round, artifact: request.artifact, role: 'reviewer' },
@@ -292,65 +196,16 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     const schema = getArtifactSchema(spec.family);
     const structure = inspectArtifactContract(artifactContent, schema);
     if (!structure.ok) {
-        if (!recovery && !request.dryRun && options.startRecovery) {
-            try {
-                recovery = beginArtifactRecovery({
-                    taskId: taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
-                    requestId: `review-finalize:${taskId}:${stage}:${parsed.round}`
-                }, Buffer.from(artifactContent, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-            }
-            catch (error) {
-                return reject('REVIEW_PROVENANCE_INVALID', String(error), digests);
-            }
-        }
-        return {
-            ...reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
-                artifactSha256, semanticDigest: structure.semanticDigest,
-                ...(recovery ? { recovery: {
-                        recoveryId: recovery.recoveryId,
-                        candidatePath: recovery.stagingPath,
-                        baselineSha256: recovery.baselineSha256,
-                        baselineSemanticDigest: recovery.baselineSemanticDigest
-                    } } : {})
-            }),
-            ...(recovery ? { recovery } : {})
-        };
+        return reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
+            artifactSha256, semanticDigest: structure.semanticDigest
+        });
     }
-    const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
+    const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts, {
+        refreshNumericCounts: true
+    });
     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);
-        return {
-            content: transformed.content,
-            result: {
-                ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', taskId, stageStatus, finalDigests),
-                status: 'no-op',
-                changed: false,
-                error: null
-            },
-            lockAlreadyHeld: options.lockAlreadyHeld
-        };
-    }
-    if (!recovery && !request.dryRun && options.startRecovery) {
-        try {
-            recovery = beginArtifactRecovery({
-                taskId: taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
-                requestId: `review-finalize:${taskId}:${stage}:${parsed.round}`
-            }, Buffer.from(artifactContent, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-        }
-        catch (error) {
-            return reject('REVIEW_PROVENANCE_INVALID', String(error), finalDigests);
-        }
-    }
     return {
         content: transformed.content,
         result: {
@@ -360,65 +215,26 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
             operations: transformed.changed ? [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }] : [],
             error: null
         },
-        ...(recovery ? { recovery } : {}),
         lockAlreadyHeld: options.lockAlreadyHeld
     };
 }
 function commitReviewSummaryProvenance(prepared, repoRoot, options = {}) {
-    if (prepared.result.status === 'failed' || !prepared.recovery)
-        return prepared.result;
+    return prepared.result;
+}
+function replaceCurrentArtifactAtomically(file, content) {
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
     try {
-        const intent = readArtifactRecoveryIntent(prepared.recovery.repoRoot, prepared.recovery.taskId, prepared.recovery.family, prepared.recovery.artifact);
-        if (!intent)
-            throw new Error('ARTIFACT_RECOVERY_INTENT_MISSING');
-        let committed;
-        if (intent.state === 'passed' || intent.state === 'consumed') {
-            return {
-                ...prepared.result,
-                status: 'no-op',
-                changed: false,
-                artifactSha256: intent.finalArtifactSha256,
-                semanticDigest: intent.finalSemanticDigest,
-                error: null
-            };
-        }
-        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 });
-        }
-        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 });
+        fs.writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx' });
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporary);
         }
-        else if (intent.state === 'full-finalizer-ready') {
-            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
         }
-        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,
-            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: 'REVIEW_RECOVERY_COMMIT_FAILED', message: `cannot publish review candidate: ${String(error)}`
-            } };
     }
 }
 function finalizeReviewSummaryUnlocked(request, options = {}) {
@@ -443,10 +259,23 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
     const prepared = prepareReviewSummaryCandidate(request, content, options);
     if (request.dryRun)
         return prepared.result;
-    return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
+    if (prepared.result.status === 'failed' || !prepared.result.changed)
+        return prepared.result;
+    try {
+        replaceCurrentArtifactAtomically(validated.artifact.path, prepared.content);
+        return {
+            ...prepared.result,
+            status: 'applied',
+            artifactSha256: sha256Content(prepared.content),
+            semanticDigest: canonicalSemanticDigest(prepared.content)
+        };
+    }
+    catch (error) {
+        return failed(request, 'REVIEW_RECOVERY_COMMIT_FAILED', `cannot update current review artifact: ${error instanceof Error ? error.message : String(error)}`, resolved.taskId);
+    }
 }
 function finalizeReviewSummary(request, options = {}) {
-    const effectiveOptions = { ...options, startRecovery: !request.dryRun };
+    const effectiveOptions = options;
     if (request.dryRun || options.lockAlreadyHeld)
         return finalizeReviewSummaryUnlocked(request, effectiveOptions);
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });

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

@@ -9,10 +9,13 @@ export const TASK_WORKFLOW_COMMANDS = Object.freeze({
     'ledger-finding-response': ['task-ledger', 'finding-respond'],
     'ledger-finding-review': ['task-ledger', 'finding-review'],
     'ledger-finding-upsert': ['task-ledger', 'finding-upsert'],
+    'ledger-stage-status': ['task-ledger', 'stage-status'],
     'decision-next-id': ['task-ledger', 'decision-next-id'],
     'decision-upsert': ['task-ledger', 'decision-upsert'],
     'invalidation-reconcile': ['task-invalidation', 'reconcile'],
-    'warning-add': ['task-warning', 'add']
+    'warning-add': ['task-warning', 'add'],
+    'warning-list': ['task-warning', 'list'],
+    'warning-set-status': ['task-warning', 'set-status']
 });
 export const TASK_WORKFLOW_OPERATIONS = Object.freeze(Object.keys(TASK_WORKFLOW_COMMANDS));
 //# sourceMappingURL=workflow-command.js.map

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

@@ -1,5 +1,8 @@
+import fs from 'node:fs';
 import { reconcileTaskInvalidation } from './invalidation-command.js';
 import { applyLedgerIntent } from './ledger-intents.js';
+import { isReviewStage, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
+import { resolveTaskRef } from './resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 import { applyWorkflowWarningIntent } from './workflow-warning-intents.js';
 function failed(code, message) {
@@ -102,8 +105,27 @@ function ledgerIntent(operation, args) {
 }
 function warningIntent(args) {
     const [taskRef, kind] = args;
-    if (!taskRef || kind !== 'add')
+    if (!taskRef || !['add', 'list', 'set-status'].includes(kind ?? '')) {
         return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task workflow warning request is invalid');
+    }
+    if (kind === 'list') {
+        const values = options(args, { '--status': 'status' });
+        if (isFailure(values))
+            return values;
+        return { kind, taskRef, ...(value(values, '--status') ? { status: value(values, '--status') } : {}) };
+    }
+    if (kind === 'set-status') {
+        const values = options(args, { '--id': 'id', '--status': 'status', '--resolution': 'resolution', '--dry-run': 'dryRun' });
+        if (isFailure(values))
+            return values;
+        const missing = required(values, ['--id', '--status', '--resolution']);
+        if (missing)
+            return missing;
+        return {
+            kind, taskRef, id: value(values, '--id'), status: value(values, '--status'),
+            resolution: value(values, '--resolution'), ...(values['--dry-run'] === true ? { dryRun: true } : {})
+        };
+    }
     const values = options(args, {
         '--step': 'step', '--severity': 'severity', '--code': 'code', '--target': 'target',
         '--message': 'message', '--action': 'action', '--dry-run': 'dryRun'
@@ -119,6 +141,32 @@ function warningIntent(args) {
         action: value(values, '--action'), ...(values['--dry-run'] === true ? { dryRun: true } : {})
     };
 }
+function stageStatus(repoRoot, args) {
+    const [taskRef, kind] = args;
+    if (!taskRef || kind !== 'stage-status')
+        return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task workflow ledger request is invalid');
+    const values = options(args, { '--stage': 'stage' });
+    if (isFailure(values))
+        return values;
+    const stage = value(values, '--stage');
+    if (!stage || !isReviewStage(stage))
+        return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'stage-status requires a valid review stage');
+    const resolved = resolveTaskRef(taskRef, { repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message);
+    try {
+        const ledger = parseLedgerDocument(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+        if (!ledger.present)
+            return failed('LEDGER_SECTION_MISSING', 'review disagreement ledger section is missing');
+        const invalid = validateLedgerRows(ledger.rows);
+        if (invalid)
+            return failed(invalid.code, invalid.message);
+        return { status: 'ready', changed: false, taskId: resolved.taskId, stageStatus: summarizeLedgerStage(ledger.rows, stage), error: null };
+    }
+    catch (error) {
+        return failed('LEDGER_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error));
+    }
+}
 /**
  * The caller has already selected and authorized the execution boundary.
  * This function deliberately invokes task domains in that process: starting a
@@ -143,11 +191,15 @@ export function dispatchWorkflowCommand(repoRoot, operation, args) {
                 ...(values['--dry-run'] === true ? { dryRun: true } : {})
             }));
         }
-        if (operation === 'warning-add') {
+        if (operation === 'ledger-stage-status')
+            return stageStatus(repoRoot, args);
+        if (operation === 'warning-add' || operation === 'warning-list' || operation === 'warning-set-status') {
             const intent = warningIntent(args);
             if (isFailure(intent))
                 return intent;
-            return withTaskExecutionLock(repoRoot, taskRef, 'task-warning.add', () => applyWorkflowWarningIntent(intent, { repoRoot }));
+            if (intent.kind === 'list')
+                return applyWorkflowWarningIntent(intent, { repoRoot });
+            return withTaskExecutionLock(repoRoot, taskRef, `task-warning.${intent.kind}`, () => applyWorkflowWarningIntent(intent, { repoRoot }));
         }
         const intent = ledgerIntent(operation, args);
         if (isFailure(intent))

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.11.0",
-  "sourceInputHash": "c67e66a46040d5246d67c751af605b796cd61913b98add01ff327829c01ce3db",
-  "internalExecutableBuildHash": "f6b4be06df12111b3a7614d335c9e802049c3cea194c6e7c040f3251188c694f"
+  "packageVersion": "0.11.2",
+  "sourceInputHash": "0a1ffa8b90a0d157f9b2aabea6a43f946d68a622bde337befe71059f63b3812b",
+  "internalExecutableBuildHash": "b6742e1b5d1b997bf7e21e644bfde2bafaa608f7ede7ca308ff61c2cd19da831"
 }

package/lib/internal/cli-route-inventory.ts

@@ -46,7 +46,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'platform-security': ['read', 'dismiss'],
   'platform-metadata': ['init-labels', 'init-milestones'],
   'platform-context': ['resolve'],
-  'platform-comment': ['list', 'recover', 'owner', 'backfill', 'sync'],
+  'platform-comment': ['list', 'recover', 'owner', 'backfill', 'stage-summary', 'sync'],
   'platform-issue': ['inspect', 'create', 'bind', 'sync'],
   'platform-pr': ['inspect', 'summary-context', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'change-report', 'summary-sync', 'sync-in-labels'],
   'platform-pr-review': ['inspect', 'list', 'publish-pr', 'publish-task'],