codex-workflow-v2 2.0.0-alpha.4 → 2.0.0-alpha.6

package/dist/src/alpha6/plan-risk.js

@@ -0,0 +1,847 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { WorkflowError } from '../errors.js';
+import { assertHash64, canonicalJsonStringify, sha256Hex } from './store-sidecars.js';
+import { createUlid } from '../ulid.js';
+const PLAN_RISK_AUDIT_SIDECAR = 'plan-risk-audits.jsonl';
+const ADOPTION_POSTURE_SIDECAR = 'adoption-posture.jsonl';
+const PLAN_RISK_DECISIONS = new Set([
+    'approved',
+    'approved-with-rationale',
+    'split-required',
+    'stop-escalate',
+]);
+const ADOPTION_POSTURE_EVENT_TYPES = new Set([
+    'project-registration',
+    'adoption-apply',
+]);
+const ACTIVE_ADOPTION_TASK_STATUSES = new Set([
+    'planning',
+    'awaiting_execution_authorization',
+    'ready',
+    'in_progress',
+    'validating',
+    'needs_fix',
+    'awaiting_final_acceptance',
+    'blocked',
+]);
+const PLAN_RISK_RECORDABLE_TASK_STATUSES = new Set([
+    'awaiting_execution_authorization',
+    'ready',
+    'in_progress',
+    'validating',
+    'needs_fix',
+    'awaiting_final_acceptance',
+    'blocked',
+]);
+const GUARDED_RISK_CATEGORY_ORDER = [
+    'migration',
+    'concurrency',
+    'restart-replay',
+    'crash-window',
+    'external-provider',
+    'runtime-composition',
+    'security-boundary',
+    'auth-secrets',
+    'irreversible-execution',
+];
+const GUARDED_RISK_CATEGORY_SET = new Set(GUARDED_RISK_CATEGORY_ORDER);
+const GUARDED_RISK_CATEGORY_INDEX = new Map(GUARDED_RISK_CATEGORY_ORDER.map((category, index) => [category, index]));
+export function validatePlanRiskAuditCandidate(store, task, input) {
+    const boundary = readPlanRiskAuditBoundary(store, task);
+    if (!boundary) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit requires an active adoption posture boundary.', {
+            taskId: task.id,
+        });
+    }
+    assertRecordableTask(task);
+    if (!task.planHash || task.knowledgeMapRevision === null || !task.knowledgeMapHash) {
+        throw new WorkflowError('STATE_CORRUPT', 'Candidate Task is missing Plan or Knowledge bindings for risk audit.', {
+            taskId: task.id,
+        });
+    }
+    validatePlanRiskAuditPayload(task, {
+        taskId: task.id,
+        taskRevision: task.revision + 1,
+        briefHash: task.briefHash,
+        planHash: task.planHash,
+        knowledgeMapRevision: task.knowledgeMapRevision,
+        knowledgeMapHash: task.knowledgeMapHash,
+        planner: input.planner,
+        auditor: input.auditor,
+        summary: input.summary,
+        decision: input.decision,
+        splitRationale: input.splitRationale,
+        stepClassifications: input.stepClassifications,
+    }, boundary.expectedStepIds, 'INVALID_ARGUMENT', {
+        taskId: task.id,
+        expectedStepIds: boundary.expectedStepIds,
+    });
+}
+export function readPlanRiskAuditBoundary(store, task) {
+    const posture = readCurrentAdoptionPosture(store, task.projectId);
+    if (!posture)
+        return null;
+    const scope = derivePlanRiskScope(task, posture);
+    return {
+        scope: scope.scope,
+        postureEventType: posture.eventType,
+        adoptionBoundaryAt: posture.adoptionBoundaryAt,
+        expectedStepIds: scope.expectedStepIds,
+    };
+}
+export function readCurrentPlanRiskAudit(store, task, options = {}) {
+    const boundary = readPlanRiskAuditBoundary(store, task);
+    if (!boundary)
+        return null;
+    const taskRoot = store.taskRoot(task.projectId, task.id);
+    const events = store.readSidecarEvents(taskRoot, PLAN_RISK_AUDIT_SIDECAR, {
+        validateEvent: (event, context) => validateStoredPlanRiskAuditEvent(event, task, context.file, context.line),
+    });
+    const audit = events.at(-1);
+    if (!audit) {
+        throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} requires a current Plan Risk Audit before execution can proceed.`, {
+            taskId: task.id,
+            scope: boundary.scope,
+            expectedStepIds: boundary.expectedStepIds,
+            sidecar: PLAN_RISK_AUDIT_SIDECAR,
+        });
+    }
+    const reviewRequiredStepIds = validateCurrentPlanRiskAudit(store, task, audit, boundary.expectedStepIds, options);
+    return {
+        ...boundary,
+        audit,
+        reviewRequiredStepIds,
+    };
+}
+export function buildPlanRiskAuditEvent(store, task, input, recordedAt, now = Date.now()) {
+    const boundary = readPlanRiskAuditBoundary(store, task);
+    if (!boundary) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit recording requires an active adoption posture boundary.', { taskId: task.id, sidecar: ADOPTION_POSTURE_SIDECAR });
+    }
+    assertRecordableTask(task);
+    const entityRoot = store.taskRoot(task.projectId, task.id);
+    const briefHash = store.hashArtifact(entityRoot, 'brief.md');
+    const planHash = store.hashArtifact(entityRoot, 'plan.md');
+    if (task.briefHash !== briefHash || task.planHash !== planHash) {
+        throw new WorkflowError('STATE_CORRUPT', 'Task state does not match the current Brief or Plan artifacts required for Plan Risk Audit recording.', {
+            taskId: task.id,
+            stateBriefHash: task.briefHash,
+            currentBriefHash: briefHash,
+            statePlanHash: task.planHash,
+            currentPlanHash: planHash,
+        });
+    }
+    if (task.knowledgeMapRevision === null || !task.knowledgeMapHash) {
+        throw new WorkflowError('STATE_CORRUPT', `Task ${task.id} has no current knowledge binding for Plan Risk Audit.`);
+    }
+    const event = {
+        eventId: `PRA-${createUlid(now)}`,
+        recordedAt,
+        taskId: task.id,
+        taskRevision: task.revision,
+        briefHash,
+        planHash,
+        knowledgeMapRevision: task.knowledgeMapRevision,
+        knowledgeMapHash: task.knowledgeMapHash,
+        planner: normalizeNonEmptyString(input.planner, 'Plan Risk Audit planner'),
+        auditor: normalizeNonEmptyString(input.auditor, 'Plan Risk Audit auditor'),
+        summary: normalizeNonEmptyString(input.summary, 'Plan Risk Audit summary'),
+        decision: normalizePlanRiskDecision(input.decision, 'INVALID_ARGUMENT', {
+            taskId: task.id,
+            value: input.decision,
+        }),
+        splitRationale: normalizeOptionalNonEmptyString(input.splitRationale, 'Plan Risk Audit splitRationale'),
+        stepClassifications: normalizePlanRiskClassifications(input.stepClassifications, 'INVALID_ARGUMENT', {
+            taskId: task.id,
+        }),
+    };
+    validatePlanRiskAuditPayload(task, event, boundary.expectedStepIds, 'INVALID_ARGUMENT', {
+        taskId: task.id,
+        expectedStepIds: boundary.expectedStepIds,
+    });
+    return {
+        boundary,
+        entityRoot,
+        event,
+    };
+}
+export function appendCurrentPlanRiskAudit(store, task, input, now) {
+    const prepared = buildPlanRiskAuditEvent(store, task, input, now.toISOString(), now.getTime());
+    const existingEvents = readStoredPlanRiskAuditEvents(store, task);
+    assertPlanRiskAuditAppendAllowed(task, prepared.boundary, existingEvents);
+    return store.appendSidecarEvent(prepared.entityRoot, PLAN_RISK_AUDIT_SIDECAR, prepared.event, {
+        validateEvent: (event, context) => validateStoredPlanRiskAuditEvent(event, task, context.file, context.line),
+    });
+}
+export function appendReboundPlanRiskAudit(store, sourceTask, reboundTask, sourceAudit, now) {
+    assertReboundPlanRiskAuditAllowed(store, sourceTask, reboundTask, sourceAudit);
+    return appendCurrentPlanRiskAudit(store, reboundTask, {
+        planner: sourceAudit.audit.planner,
+        auditor: sourceAudit.audit.auditor,
+        summary: `${sourceAudit.audit.summary} Rebound automatically after content-only Task context refresh.`,
+        decision: sourceAudit.audit.decision,
+        splitRationale: sourceAudit.audit.splitRationale,
+        stepClassifications: sourceAudit.audit.stepClassifications.map((classification) => ({
+            ...classification,
+            categories: [...classification.categories],
+            failureModes: [...classification.failureModes],
+            requiredEvidence: [...classification.requiredEvidence],
+        })),
+    }, now);
+}
+function readCurrentAdoptionPosture(store, projectId) {
+    const sidecarFile = path.join(store.projectRoot(projectId), ADOPTION_POSTURE_SIDECAR);
+    if (!existsSync(sidecarFile))
+        return null;
+    const events = store.readSidecarEvents(store.projectRoot(projectId), ADOPTION_POSTURE_SIDECAR, {
+        validateEvent: (event, context) => validateStoredAdoptionPostureEvent(event, projectId, context.file, context.line),
+    });
+    return events.at(-1) ?? null;
+}
+function assertReboundPlanRiskAuditAllowed(store, sourceTask, reboundTask, sourceAudit) {
+    if (sourceTask.projectId !== reboundTask.projectId || sourceTask.id !== reboundTask.id) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit rebound requires the same Task identity before and after content-only refresh.', {
+            sourceTaskId: sourceTask.id,
+            reboundTaskId: reboundTask.id,
+            sourceProjectId: sourceTask.projectId,
+            reboundProjectId: reboundTask.projectId,
+        });
+    }
+    if (sourceTask.briefHash !== reboundTask.briefHash) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit rebound is limited to content-only refresh and cannot cross a Brief change.', {
+            taskId: sourceTask.id,
+            sourceBriefHash: sourceTask.briefHash,
+            reboundBriefHash: reboundTask.briefHash,
+        });
+    }
+    if (sourceTask.planHash === reboundTask.planHash) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit rebound requires a current rebound Plan binding.', {
+            taskId: sourceTask.id,
+            planHash: sourceTask.planHash,
+        });
+    }
+    if (sourceTask.knowledgeMapRevision === reboundTask.knowledgeMapRevision
+        && sourceTask.knowledgeMapHash === reboundTask.knowledgeMapHash) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit rebound requires a changed Task knowledge binding.', {
+            taskId: sourceTask.id,
+            knowledgeMapRevision: sourceTask.knowledgeMapRevision,
+            knowledgeMapHash: sourceTask.knowledgeMapHash,
+        });
+    }
+    const reboundBoundary = readPlanRiskAuditBoundary(store, reboundTask);
+    if (!reboundBoundary) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit rebound requires an active adoption posture boundary.', {
+            taskId: reboundTask.id,
+            sidecar: ADOPTION_POSTURE_SIDECAR,
+        });
+    }
+    assertExactIdSet(sourceAudit.expectedStepIds, reboundBoundary.expectedStepIds, 'TRANSITION_BLOCKED', 'Plan Risk Audit rebound requires the exact same classified Step set after content-only refresh.', {
+        taskId: reboundTask.id,
+        sourceExpectedStepIds: sourceAudit.expectedStepIds,
+        reboundExpectedStepIds: reboundBoundary.expectedStepIds,
+    });
+    const sourceStepDefinitions = buildTaskStepDefinitionHashes(sourceTask);
+    const reboundStepDefinitions = buildTaskStepDefinitionHashes(reboundTask);
+    assertExactIdSet([...sourceStepDefinitions.keys()], [...reboundStepDefinitions.keys()], 'TRANSITION_BLOCKED', 'Plan Risk Audit rebound requires the same Task Step identifiers after content-only refresh.', {
+        taskId: reboundTask.id,
+        sourceStepIds: [...sourceStepDefinitions.keys()],
+        reboundStepIds: [...reboundStepDefinitions.keys()],
+    });
+    for (const [stepId, sourceDefinitionHash] of sourceStepDefinitions.entries()) {
+        if (reboundStepDefinitions.get(stepId) === sourceDefinitionHash)
+            continue;
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit rebound is limited to content-only refresh and cannot cross a Step definition change.', {
+            taskId: reboundTask.id,
+            stepId,
+            sourceDefinitionHash,
+            reboundDefinitionHash: reboundStepDefinitions.get(stepId) ?? null,
+        });
+    }
+}
+function derivePlanRiskScope(task, posture) {
+    const currentTaskStepIds = task.steps.map((step) => step.id);
+    assertUniqueValues(currentTaskStepIds, 'STATE_CORRUPT', 'Task contains duplicate Step identifiers.', {
+        taskId: task.id,
+        stepIds: currentTaskStepIds,
+    });
+    const baseline = posture.activeTasks.find((candidate) => candidate.taskId === task.id) ?? null;
+    if (!baseline) {
+        return {
+            scope: 'current-task-steps',
+            expectedStepIds: currentTaskStepIds,
+        };
+    }
+    validateAdoptionBaseline(task, baseline, currentTaskStepIds, posture);
+    const completedStepIdSet = new Set(baseline.completedSteps.map((step) => step.stepId));
+    return {
+        scope: 'legacy-remaining-scope',
+        expectedStepIds: currentTaskStepIds.filter((stepId) => !completedStepIdSet.has(stepId)),
+    };
+}
+function validateStoredAdoptionPostureEvent(event, expectedProjectId, file, line) {
+    assertPlainObject(event, 'Adoption posture event', file, line);
+    const eventType = normalizeAdoptionPostureEventType(event.eventType, file, line, event.eventId);
+    if (event.projectId !== expectedProjectId) {
+        throw new WorkflowError('STATE_CORRUPT', 'Adoption posture event project binding does not match its project root.', {
+            file,
+            line,
+            eventId: event.eventId,
+            expectedProjectId,
+            actualProjectId: event.projectId,
+        });
+    }
+    normalizeNonEmptyString(event.adoptionBoundaryAt, 'Adoption posture adoptionBoundaryAt', {
+        code: 'STATE_CORRUPT',
+        file,
+        line,
+        eventId: event.eventId,
+    });
+    if (!Array.isArray(event.activeTasks)) {
+        throw new WorkflowError('STATE_CORRUPT', 'Adoption posture activeTasks must be an array.', {
+            file,
+            line,
+            eventId: event.eventId,
+            eventType,
+        });
+    }
+    assertUniqueValues(event.activeTasks.map((candidate) => candidate?.taskId), 'STATE_CORRUPT', 'Adoption posture contains duplicate active Task baselines.', { file, line, eventId: event.eventId });
+    for (const baseline of event.activeTasks) {
+        validateStoredAdoptionTaskBaseline(baseline, file, line, event.eventId);
+    }
+}
+function validateStoredAdoptionTaskBaseline(baseline, file, line, eventId) {
+    assertPlainObject(baseline, 'Adoption Task baseline', file, line);
+    normalizeNonEmptyString(baseline.taskId, 'Adoption Task baseline taskId', {
+        code: 'STATE_CORRUPT',
+        file,
+        line,
+        eventId,
+    });
+    assertPositiveInteger(baseline.taskRevision, 'Adoption Task baseline taskRevision', file, line, eventId);
+    if (!ACTIVE_ADOPTION_TASK_STATUSES.has(baseline.status)) {
+        throw new WorkflowError('STATE_CORRUPT', 'Adoption Task baseline status is invalid.', {
+            file,
+            line,
+            eventId,
+            taskId: baseline.taskId,
+            status: baseline.status,
+        });
+    }
+    if (!Array.isArray(baseline.completedSteps)) {
+        throw new WorkflowError('STATE_CORRUPT', 'Adoption Task baseline completedSteps must be an array.', {
+            file,
+            line,
+            eventId,
+            taskId: baseline.taskId,
+        });
+    }
+    if (!Array.isArray(baseline.remainingStepIds)) {
+        throw new WorkflowError('STATE_CORRUPT', 'Adoption Task baseline remainingStepIds must be an array.', {
+            file,
+            line,
+            eventId,
+            taskId: baseline.taskId,
+        });
+    }
+    const completedStepIds = [];
+    for (const completed of baseline.completedSteps) {
+        assertPlainObject(completed, 'Adoption completed Step baseline', file, line);
+        const stepId = normalizeNonEmptyString(completed.stepId, 'Adoption completed Step stepId', {
+            code: 'STATE_CORRUPT',
+            file,
+            line,
+            eventId,
+            taskId: baseline.taskId,
+        });
+        completedStepIds.push(stepId);
+        if (completed.status !== 'completed' && completed.status !== 'skipped') {
+            throw new WorkflowError('STATE_CORRUPT', 'Adoption completed Step status is invalid.', {
+                file,
+                line,
+                eventId,
+                taskId: baseline.taskId,
+                stepId,
+                status: completed.status,
+            });
+        }
+        if (completed.evidenceHash !== null) {
+            if (typeof completed.evidenceHash !== 'string') {
+                throw new WorkflowError('STATE_CORRUPT', 'Adoption completed Step evidenceHash must be null or a hash.', {
+                    file,
+                    line,
+                    eventId,
+                    taskId: baseline.taskId,
+                    stepId,
+                    evidenceHash: completed.evidenceHash,
+                });
+            }
+            assertHash64(completed.evidenceHash, 'Adoption completed Step evidenceHash');
+        }
+    }
+    assertUniqueValues(completedStepIds, 'STATE_CORRUPT', 'Adoption completed Step baseline must not contain duplicates.', {
+        file,
+        line,
+        eventId,
+        taskId: baseline.taskId,
+    });
+    const remainingStepIds = baseline.remainingStepIds.map((stepId) => normalizeNonEmptyString(stepId, 'Adoption remaining Step id', {
+        code: 'STATE_CORRUPT',
+        file,
+        line,
+        eventId,
+        taskId: baseline.taskId,
+    }));
+    assertUniqueValues(remainingStepIds, 'STATE_CORRUPT', 'Adoption posture remaining Step baseline must not contain duplicates.', {
+        file,
+        line,
+        eventId,
+        taskId: baseline.taskId,
+    });
+    const completedSet = new Set(completedStepIds);
+    const overlap = remainingStepIds.filter((stepId) => completedSet.has(stepId));
+    if (overlap.length > 0) {
+        throw new WorkflowError('STATE_CORRUPT', 'Adoption Task baseline cannot list the same Step as both completed and remaining.', {
+            file,
+            line,
+            eventId,
+            taskId: baseline.taskId,
+            overlappingStepIds: overlap,
+        });
+    }
+}
+function validateAdoptionBaseline(task, baseline, currentTaskStepIds, posture) {
+    if (baseline.taskRevision > task.revision) {
+        throw new WorkflowError('STATE_CORRUPT', 'Adoption posture baseline refers to a future Task revision.', {
+            taskId: task.id,
+            baselineTaskRevision: baseline.taskRevision,
+            currentTaskRevision: task.revision,
+            adoptionBoundaryAt: posture.adoptionBoundaryAt,
+        });
+    }
+    const currentTaskStepIdSet = new Set(currentTaskStepIds);
+    const completedStepIds = baseline.completedSteps.map((step) => step.stepId);
+    const completedStepIdSet = new Set(completedStepIds);
+    const missingCompletedFromTask = completedStepIds.filter((stepId) => !currentTaskStepIdSet.has(stepId));
+    if (missingCompletedFromTask.length > 0) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Adoption posture remaining-scope baseline no longer matches the current Task Step set.', {
+            taskId: task.id,
+            adoptionBoundaryAt: posture.adoptionBoundaryAt,
+            missingCompletedStepIds: missingCompletedFromTask,
+        });
+    }
+    const overlap = baseline.remainingStepIds.filter((stepId) => completedStepIdSet.has(stepId));
+    if (overlap.length > 0) {
+        throw new WorkflowError('STATE_CORRUPT', 'Adoption posture baseline cannot mark the same Step as completed and remaining.', {
+            taskId: task.id,
+            adoptionBoundaryAt: posture.adoptionBoundaryAt,
+            overlappingStepIds: overlap,
+        });
+    }
+    if (baseline.taskRevision === task.revision) {
+        const missingRemainingFromTask = baseline.remainingStepIds.filter((stepId) => !currentTaskStepIdSet.has(stepId));
+        if (missingRemainingFromTask.length > 0) {
+            throw new WorkflowError('TRANSITION_BLOCKED', 'Adoption posture remaining-scope baseline no longer matches the Task Step set at the posture boundary revision.', {
+                taskId: task.id,
+                adoptionBoundaryAt: posture.adoptionBoundaryAt,
+                missingStepIds: missingRemainingFromTask,
+            });
+        }
+        const partitionIds = [...completedStepIds, ...baseline.remainingStepIds];
+        assertExactIdSet(currentTaskStepIds, partitionIds, 'STATE_CORRUPT', 'Adoption posture baseline must partition the Task Step set at the posture boundary revision.', {
+            taskId: task.id,
+            adoptionBoundaryAt: posture.adoptionBoundaryAt,
+            currentTaskRevision: task.revision,
+            completedStepIds,
+            remainingStepIds: baseline.remainingStepIds,
+        });
+    }
+}
+function validateStoredPlanRiskAuditEvent(event, task, file, line) {
+    validatePlanRiskAuditPayload(task, event, null, 'STATE_CORRUPT', {
+        file,
+        line,
+        eventId: event.eventId,
+    });
+}
+function validatePlanRiskAuditPayload(task, event, expectedStepIds, errorCode, details) {
+    if (event.taskId !== task.id) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit task binding does not match its task root.', {
+            ...details,
+            expectedTaskId: task.id,
+            actualTaskId: event.taskId,
+        });
+    }
+    assertPositiveInteger(event.taskRevision, 'Plan Risk Audit taskRevision', details.file, details.line, details.eventId, errorCode);
+    assertHash64String(event.briefHash, 'Plan Risk Audit briefHash', errorCode, details);
+    assertHash64String(event.planHash, 'Plan Risk Audit planHash', errorCode, details);
+    assertPositiveInteger(event.knowledgeMapRevision, 'Plan Risk Audit knowledgeMapRevision', details.file, details.line, details.eventId, errorCode);
+    assertHash64String(event.knowledgeMapHash, 'Plan Risk Audit knowledgeMapHash', errorCode, details);
+    const planner = normalizeNonEmptyString(event.planner, 'Plan Risk Audit planner', { code: errorCode, ...details });
+    const auditor = normalizeNonEmptyString(event.auditor, 'Plan Risk Audit auditor', { code: errorCode, ...details });
+    if (planner === auditor) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit auditor must be independent from the Plan author.', {
+            ...details,
+            taskId: task.id,
+            planner,
+            auditor,
+        });
+    }
+    normalizeNonEmptyString(event.summary, 'Plan Risk Audit summary', { code: errorCode, ...details });
+    normalizePlanRiskDecision(event.decision, errorCode, details);
+    normalizeOptionalNonEmptyString(event.splitRationale, 'Plan Risk Audit splitRationale', { code: errorCode, ...details });
+    if (!Array.isArray(event.stepClassifications)) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit stepClassifications must be an array.', details);
+    }
+    validateStepClassificationSet(task, event.stepClassifications, event.decision, event.splitRationale, expectedStepIds, errorCode, details);
+}
+function validateStepClassificationSet(task, classifications, decision, splitRationale, expectedStepIds, errorCode, details) {
+    const currentTaskStepIds = new Set(task.steps.map((step) => step.id));
+    const normalizedStepIds = classifications.map((classification) => normalizeNonEmptyString(classification?.stepId, 'Plan Risk Audit classification stepId', {
+        code: errorCode,
+        ...details,
+    }));
+    assertUniqueValues(normalizedStepIds, errorCode, 'Plan Risk Audit must classify each Step exactly once.', {
+        ...details,
+        taskId: task.id,
+    });
+    if (expectedStepIds) {
+        assertExactIdSet(expectedStepIds, normalizedStepIds, errorCode, 'Plan Risk Audit Step classifications do not match the required Step set.', {
+            ...details,
+            taskId: task.id,
+            expectedStepIds,
+            actualStepIds: normalizedStepIds,
+        });
+    }
+    let reviewRequiredCount = 0;
+    const guardedCategories = new Set();
+    for (const classification of classifications) {
+        if (expectedStepIds && !currentTaskStepIds.has(classification.stepId)) {
+            throw new WorkflowError(errorCode, 'Plan Risk Audit references a Step that is not present in the Task.', {
+                ...details,
+                taskId: task.id,
+                stepId: classification.stepId,
+            });
+        }
+        if (classification.reviewRequired)
+            reviewRequiredCount += 1;
+        validateStepClassification(task, classification, errorCode, details);
+        classification.categories.forEach((category) => guardedCategories.add(category));
+    }
+    if ((decision === 'split-required' || decision === 'stop-escalate') && reviewRequiredCount === 0) {
+        throw new WorkflowError(errorCode, `Plan Risk Audit decision ${decision} requires at least one guarded Step.`, {
+            ...details,
+            taskId: task.id,
+        });
+    }
+    const coupledRecoveryDomains = [
+        'restart-replay',
+        'crash-window',
+        'runtime-composition',
+    ].filter((category) => guardedCategories.has(category));
+    const requiresSplitRationale = guardedCategories.has('migration') && coupledRecoveryDomains.length > 0;
+    if (requiresSplitRationale && decision !== 'approved-with-rationale') {
+        throw new WorkflowError(errorCode, 'A Plan combining migration with recovery or runtime-composition risk requires approved-with-rationale.', {
+            ...details,
+            taskId: task.id,
+            guardedCategories: [...guardedCategories],
+        });
+    }
+    if (decision === 'approved-with-rationale' && !splitRationale) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit approved-with-rationale requires an explicit split rationale.', {
+            ...details,
+            taskId: task.id,
+        });
+    }
+    if (decision !== 'approved-with-rationale' && splitRationale !== null) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit splitRationale is only valid with approved-with-rationale.', {
+            ...details,
+            taskId: task.id,
+            decision,
+        });
+    }
+}
+function validateCurrentPlanRiskAudit(store, task, audit, expectedStepIds, options) {
+    const taskRoot = store.taskRoot(task.projectId, task.id);
+    const briefHash = store.hashArtifact(taskRoot, 'brief.md');
+    const planHash = store.hashArtifact(taskRoot, 'plan.md');
+    if (audit.briefHash !== briefHash || audit.planHash !== planHash) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit is stale for the current Brief or Plan.', {
+            taskId: task.id,
+            auditEventId: audit.eventId,
+            auditBriefHash: audit.briefHash,
+            currentBriefHash: briefHash,
+            auditPlanHash: audit.planHash,
+            currentPlanHash: planHash,
+        });
+    }
+    if (audit.knowledgeMapRevision !== task.knowledgeMapRevision || audit.knowledgeMapHash !== task.knowledgeMapHash) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit is stale for the current Task knowledge binding.', {
+            taskId: task.id,
+            auditEventId: audit.eventId,
+            auditKnowledgeMapRevision: audit.knowledgeMapRevision,
+            currentKnowledgeMapRevision: task.knowledgeMapRevision,
+            auditKnowledgeMapHash: audit.knowledgeMapHash,
+            currentKnowledgeMapHash: task.knowledgeMapHash,
+        });
+    }
+    if (options.requireCurrentTaskRevision && audit.taskRevision !== task.revision) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit must bind the current Task revision before execution authorization.', {
+            taskId: task.id,
+            auditEventId: audit.eventId,
+            auditTaskRevision: audit.taskRevision,
+            currentTaskRevision: task.revision,
+        });
+    }
+    if (audit.taskRevision > task.revision) {
+        throw new WorkflowError('STATE_CORRUPT', 'Plan Risk Audit refers to a future Task revision.', {
+            taskId: task.id,
+            auditEventId: audit.eventId,
+            auditTaskRevision: audit.taskRevision,
+            currentTaskRevision: task.revision,
+        });
+    }
+    validateStepClassificationSet(task, audit.stepClassifications, audit.decision, audit.splitRationale, expectedStepIds, 'TRANSITION_BLOCKED', {
+        taskId: task.id,
+        auditEventId: audit.eventId,
+        expectedStepIds,
+    });
+    if (audit.decision === 'split-required' || audit.decision === 'stop-escalate') {
+        throw new WorkflowError('TRANSITION_BLOCKED', `Plan Risk Audit decision ${audit.decision} blocks execution authorization.`, {
+            taskId: task.id,
+            auditEventId: audit.eventId,
+            decision: audit.decision,
+            requiredAction: audit.decision === 'split-required'
+                ? 'Split the guarded work into separate Tasks and replace the Plan.'
+                : 'Escalate the Plan to the coordinator before continuing.',
+        });
+    }
+    return audit.stepClassifications
+        .filter((classification) => classification.reviewRequired)
+        .map((classification) => classification.stepId);
+}
+function validateStepClassification(task, classification, errorCode, details) {
+    if (!Array.isArray(classification.categories)) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit categories must be an array.', {
+            ...details,
+            taskId: task.id,
+            stepId: classification.stepId,
+        });
+    }
+    if (typeof classification.reviewRequired !== 'boolean') {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit reviewRequired must be boolean.', {
+            ...details,
+            taskId: task.id,
+            stepId: classification.stepId,
+            reviewRequired: classification.reviewRequired,
+        });
+    }
+    const normalizedCategories = classification.categories.map((category) => normalizeGuardedRiskCategory(category, errorCode, {
+        ...details,
+        taskId: task.id,
+        stepId: classification.stepId,
+    }));
+    assertUniqueValues(normalizedCategories, errorCode, 'Plan Risk Audit categories must be unique per Step.', {
+        ...details,
+        taskId: task.id,
+        stepId: classification.stepId,
+        categories: normalizedCategories,
+    });
+    const canonicalCategories = [...normalizedCategories]
+        .sort((left, right) => compareGuardedRiskCategories(left, right));
+    if (JSON.stringify(canonicalCategories) !== JSON.stringify(normalizedCategories)) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit categories must be unique and in canonical order.', {
+            ...details,
+            taskId: task.id,
+            stepId: classification.stepId,
+            expectedCategories: canonicalCategories,
+            actualCategories: normalizedCategories,
+        });
+    }
+    const expectedReviewRequired = normalizedCategories.length > 0;
+    if (classification.reviewRequired !== expectedReviewRequired) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit reviewRequired must match category presence for each Step.', {
+            ...details,
+            taskId: task.id,
+            stepId: classification.stepId,
+            categories: normalizedCategories,
+            reviewRequired: classification.reviewRequired,
+        });
+    }
+    const failureModes = normalizeStringArray(classification.failureModes, 'Plan Risk Audit failureModes', errorCode, { ...details, taskId: task.id, stepId: classification.stepId });
+    const requiredEvidence = normalizeStringArray(classification.requiredEvidence, 'Plan Risk Audit requiredEvidence', errorCode, { ...details, taskId: task.id, stepId: classification.stepId });
+    if (expectedReviewRequired && (failureModes.length === 0 || requiredEvidence.length === 0)) {
+        throw new WorkflowError(errorCode, 'Every guarded Step must declare failure modes and required evidence.', {
+            ...details,
+            taskId: task.id,
+            stepId: classification.stepId,
+        });
+    }
+    if (!expectedReviewRequired && (failureModes.length > 0 || requiredEvidence.length > 0)) {
+        throw new WorkflowError(errorCode, 'An unguarded Step cannot declare guarded failure modes or evidence.', {
+            ...details,
+            taskId: task.id,
+            stepId: classification.stepId,
+        });
+    }
+    const step = task.steps.find((candidate) => candidate.id === classification.stepId);
+    if (step) {
+        const missingChecks = requiredEvidence.filter((evidence) => !step.checks.includes(evidence));
+        if (missingChecks.length > 0) {
+            throw new WorkflowError(errorCode, 'Plan Risk Audit required evidence must be backed by exact executable Step checks.', {
+                ...details,
+                taskId: task.id,
+                stepId: classification.stepId,
+                missingChecks,
+                declaredChecks: step.checks,
+            });
+        }
+    }
+}
+function buildTaskStepDefinitionHashes(task) {
+    return new Map(task.steps.map((step) => [step.id, sha256Hex(canonicalJsonStringify(stripTaskStepRuntime(step)))]));
+}
+function stripTaskStepRuntime(step) {
+    const { status: _status, evidence: _evidence, ...definition } = step;
+    return definition;
+}
+function assertRecordableTask(task) {
+    if (!PLAN_RISK_RECORDABLE_TASK_STATUSES.has(task.status)) {
+        throw new WorkflowError('TRANSITION_BLOCKED', `Task ${task.id} cannot record a Plan Risk Audit while ${task.status}.`, { taskId: task.id, status: task.status });
+    }
+    if (!task.planHash || task.steps.length === 0) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Plan Risk Audit recording requires a current Task Plan with explicit Steps.', { taskId: task.id, status: task.status });
+    }
+}
+function readStoredPlanRiskAuditEvents(store, task) {
+    const taskRoot = store.taskRoot(task.projectId, task.id);
+    return store.readSidecarEvents(taskRoot, PLAN_RISK_AUDIT_SIDECAR, {
+        validateEvent: (event, context) => validateStoredPlanRiskAuditEvent(event, task, context.file, context.line),
+    });
+}
+function assertPlanRiskAuditAppendAllowed(task, boundary, existingEvents) {
+    if (task.status === 'awaiting_execution_authorization')
+        return;
+    if (existingEvents.length > 0) {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Replacing a Plan Risk Audit requires returning the Task to awaiting_execution_authorization through a legitimate replan.', {
+            taskId: task.id,
+            status: task.status,
+            existingAuditCount: existingEvents.length,
+        });
+    }
+    if (boundary.scope !== 'legacy-remaining-scope') {
+        throw new WorkflowError('TRANSITION_BLOCKED', 'Mid-execution Plan Risk Audit recording is limited to the first legacy bootstrap audit.', {
+            taskId: task.id,
+            status: task.status,
+            scope: boundary.scope,
+            postureEventType: boundary.postureEventType,
+        });
+    }
+}
+function normalizePlanRiskDecision(decision, errorCode, details) {
+    if (typeof decision !== 'string' || !PLAN_RISK_DECISIONS.has(decision)) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit decision is invalid.', {
+            ...details,
+            decision,
+        });
+    }
+    return decision;
+}
+function normalizeAdoptionPostureEventType(value, file, line, eventId) {
+    if (typeof value !== 'string' || !ADOPTION_POSTURE_EVENT_TYPES.has(value)) {
+        throw new WorkflowError('STATE_CORRUPT', 'Adoption posture eventType is invalid.', {
+            file,
+            line,
+            eventId,
+            eventType: value,
+        });
+    }
+    return value;
+}
+function normalizeGuardedRiskCategory(value, errorCode, details) {
+    if (typeof value !== 'string' || !GUARDED_RISK_CATEGORY_SET.has(value)) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit category is invalid.', {
+            ...details,
+            category: value,
+        });
+    }
+    return value;
+}
+function normalizePlanRiskClassifications(value, errorCode, details) {
+    if (!Array.isArray(value)) {
+        throw new WorkflowError(errorCode, 'Plan Risk Audit stepClassifications must be an array.', details);
+    }
+    return value;
+}
+function normalizeStringArray(value, label, errorCode, details) {
+    if (!Array.isArray(value)) {
+        throw new WorkflowError(errorCode, `${label} must be an array.`, details);
+    }
+    const normalized = value.map((entry) => normalizeNonEmptyString(entry, label, { code: errorCode, ...details }));
+    assertUniqueValues(normalized, errorCode, `${label} must contain unique values.`, details);
+    return normalized;
+}
+function normalizeOptionalNonEmptyString(value, label, details = {}) {
+    if (value === null)
+        return null;
+    return normalizeNonEmptyString(value, label, details);
+}
+function normalizeNonEmptyString(value, label, details = {}) {
+    const errorCode = details.code ?? 'INVALID_ARGUMENT';
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new WorkflowError(errorCode, `${label} must be a non-empty string.`, details);
+    }
+    return value.trim();
+}
+function assertPositiveInteger(value, label, file, line, eventId, errorCode = 'STATE_CORRUPT') {
+    if (!Number.isInteger(value) || Number(value) < 1) {
+        throw new WorkflowError(errorCode, `${label} must be a positive integer.`, {
+            ...(file !== undefined ? { file } : {}),
+            ...(line !== undefined ? { line } : {}),
+            ...(eventId !== undefined ? { eventId } : {}),
+            value,
+        });
+    }
+}
+function assertHash64String(value, label, errorCode, details) {
+    if (typeof value !== 'string') {
+        throw new WorkflowError(errorCode, `${label} must be a sha256 hex digest.`, {
+            ...details,
+            value,
+        });
+    }
+    try {
+        assertHash64(value, label);
+    }
+    catch (error) {
+        if (error instanceof WorkflowError) {
+            throw new WorkflowError(errorCode, error.message, { ...details, ...error.details });
+        }
+        throw error;
+    }
+}
+function assertPlainObject(value, label, file, line) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new WorkflowError('STATE_CORRUPT', `${label} must be an object.`, { file, line });
+    }
+}
+function compareGuardedRiskCategories(left, right) {
+    return (GUARDED_RISK_CATEGORY_INDEX.get(left) ?? Number.MAX_SAFE_INTEGER)
+        - (GUARDED_RISK_CATEGORY_INDEX.get(right) ?? Number.MAX_SAFE_INTEGER);
+}
+function assertUniqueValues(values, errorCode, message, details) {
+    const unique = new Set(values);
+    if (unique.size !== values.length) {
+        throw new WorkflowError(errorCode, message, details);
+    }
+}
+function assertExactIdSet(expected, actual, errorCode, message, details) {
+    if (expected.length !== actual.length) {
+        throw new WorkflowError(errorCode, message, details);
+    }
+    const expectedSet = new Set(expected);
+    if (actual.some((value) => !expectedSet.has(value))) {
+        throw new WorkflowError(errorCode, message, details);
+    }
+}
+//# sourceMappingURL=plan-risk.js.map