@amsterdamdatalabs/enact-operator 0.1.2

package/dist/mcp/workflow.js

@@ -0,0 +1,723 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { ensureLayout, inboxFile, installRegistryFile, LAYOUT_DIRS, layoutDir, layoutPath, ledgerFile, metricsFile, reviewsFile, tasksFile, } from '../shared/core/contract.js';
+import { createEvidenceHorizon } from '../shared/core/events.js';
+import { listJobs } from '../shared/core/jobs.js';
+import { defaultClosureScope } from '../shared/workflow/closure/closureManifest.js';
+import { runContractParity } from '../shared/workflow/closure/contractParity.js';
+import { reconcileWorkflowState, DEFAULT_REVIEW_STALE_MS } from '../shared/workflow/closure/workflowReconcile.js';
+import { readContinuationState, readLogicalIdleStatus } from '../shared/workflow/continuation/continuation.js';
+import { computeReviewStaleState } from '../shared/workflow/delivery/reviewStaleness.js';
+import { evaluateStopPolicy } from '../shared/workflow/continuation/stopPolicy.js';
+import { readOperatorAuthority } from '../shared/workflow/authority/authority.js';
+import { normalizeOperatorGoal } from '../shared/workflow/activation/skillActivation.js';
+import { getRalph } from '../lanes/ralph/index.js';
+import { buildUltraworkPhaseContext, getUltrawork, linkTaskRef } from '../lanes/ultrawork/index.js';
+import { inferUltraworkPhase } from '../lanes/ultrawork/phases.js';
+import { appendLedger, listInbox, listLedger, listReviews, updateReview } from '../operator/runtime.js';
+import { applyConvergedReviewFilter, computeStaleCounts } from '../operator/hud.js';
+import { readSession } from '../shared/state/session.js';
+import { readTeam } from '../lanes/team/index.js';
+import { createTask, getTask, listTasks, updateTask } from '../shared/state/tasks.js';
+import { handled, requiredString, UNHANDLED } from '../mcp/laneSupport.js';
+import { ultraworkToolDefinitions } from '../mcp/lanes/ultrawork.js';
+export const SNAPSHOT_RECENT_OPEN_LIMIT = 5;
+export const SNAPSHOT_RECENT_REVIEW_LIMIT = 10;
+export const SNAPSHOT_FIELDS = [
+    'view',
+    'staleCounts',
+    'session',
+    'autopilot',
+    'ultrawork',
+    'ralph',
+    'activeSkill',
+    'inbox',
+    'activeTasks',
+    'team',
+    'recentReviews',
+    'goalScope',
+    'unresolvedContractGaps',
+    'stopSafety',
+    'activeJobs',
+    'continuation',
+    'logicalIdle',
+];
+export function asSnapshotFieldSet() {
+    return new Set(SNAPSHOT_FIELDS);
+}
+export function activeGoalForMode(mode, ralph, ultrawork) {
+    if (mode === 'ralph') {
+        return ralph?.active ? ralph.goal : null;
+    }
+    return ultrawork?.active ? ultrawork.intent : null;
+}
+function snapshotPaths(root) {
+    const base = layoutDir(root);
+    const dirs = LAYOUT_DIRS.map((dirName) => layoutPath(root, dirName));
+    const seeds = [
+        tasksFile(root),
+        reviewsFile(root),
+        inboxFile(root),
+        ledgerFile(root),
+        installRegistryFile(root),
+        metricsFile(root),
+    ];
+    return [base, ...dirs, ...seeds].filter((path) => existsSync(path));
+}
+function collectBootstrapValidationErrors(root) {
+    const errors = [];
+    const validators = [
+        ['state/tasks.json', () => listTasks(root)],
+        ['state/reviews.json', () => listReviews(root)],
+        ['state/inbox.json', () => listInbox(root)],
+        ['logs/ledger.json', () => listLedger(root, 1)],
+        ['sessions/current.json', () => readSession(root)],
+        ['state/ralph.json', () => getRalph(root)],
+        ['state/ultrawork.json', () => getUltrawork(root)],
+        ['team/team.json', () => readTeam(root)],
+    ];
+    for (const [label, validate] of validators) {
+        try {
+            validate();
+        }
+        catch (error) {
+            errors.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return errors;
+}
+function bootstrapStatus(root) {
+    const dirPresent = [];
+    const dirMissing = [];
+    for (const dirName of LAYOUT_DIRS) {
+        const path = layoutPath(root, dirName);
+        (existsSync(path) ? dirPresent : dirMissing).push(dirName);
+    }
+    const seedEntries = [
+        ['state/tasks.json', tasksFile(root)],
+        ['state/reviews.json', reviewsFile(root)],
+        ['state/inbox.json', inboxFile(root)],
+        ['logs/ledger.json', ledgerFile(root)],
+        ['state/install-registry.json', installRegistryFile(root)],
+        ['metrics.json', metricsFile(root)],
+    ];
+    const seedPresent = [];
+    const seedMissing = [];
+    for (const [label, path] of seedEntries) {
+        (existsSync(path) ? seedPresent : seedMissing).push(label);
+    }
+    return {
+        present: dirPresent,
+        missing: dirMissing,
+        totalRequired: LAYOUT_DIRS.length,
+        seedFiles: { present: seedPresent, missing: seedMissing },
+        validationErrors: collectBootstrapValidationErrors(root),
+    };
+}
+function composeOperatorSnapshot(authority, view = 'converged') {
+    const { session, autopilot, ralph, ultrawork, team, tasks: allTasks, reviews: allReviews, inbox, operatorActive } = authority;
+    const openItems = inbox.filter((item) => item.status === 'open');
+    const recentOpen = openItems
+        .slice()
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+        .slice(0, SNAPSHOT_RECENT_OPEN_LIMIT);
+    const activeTasks = allTasks.filter((task) => task.status === 'pending' || task.status === 'queued' || task.status === 'in_progress' || task.status === 'review');
+    const filteredReviews = view === 'converged'
+        ? applyConvergedReviewFilter(allReviews)
+        : allReviews;
+    const recentReviews = filteredReviews
+        .slice()
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+        .slice(0, SNAPSHOT_RECENT_REVIEW_LIMIT);
+    const goalScope = autopilot?.goalScope ??
+        ralph?.goalScope ??
+        ultrawork?.goalScope ??
+        null;
+    const staleCounts = computeStaleCounts(allReviews, listTasks(authority.root));
+    const continuation = readContinuationState(authority.root);
+    const logicalIdle = readLogicalIdleStatus(authority.root);
+    let phaseStale = false;
+    if (ultrawork && ultrawork.active) {
+        const phaseContext = buildUltraworkPhaseContext(ultrawork, allReviews, authority.root);
+        const phaseInference = inferUltraworkPhase(phaseContext);
+        phaseStale = phaseInference.inferredPhase !== null
+            && phaseInference.inferredPhase !== ultrawork.phase
+            && !phaseInference.blockedByTransitionGuard;
+    }
+    const allJobs = listJobs(authority.root);
+    const scheduledJobs = allJobs.filter((job) => job.status === 'scheduled');
+    const pausedJobs = allJobs.filter((job) => job.status === 'paused');
+    const monitorJobs = allJobs.filter((job) => job.kind === 'monitor' && job.status === 'scheduled');
+    const nextFireAt = scheduledJobs
+        .filter((job) => job.scheduledFor !== undefined)
+        .map((job) => job.scheduledFor)
+        .sort()[0];
+    const linkedJobsForLane = (laneId) => {
+        if (!laneId)
+            return [];
+        return allJobs.filter((job) => job.status !== 'cancelled'
+            && job.linkage
+            && (job.linkage.modeId === laneId || job.linkage.taskId === laneId));
+    };
+    const autopilotWithJobs = autopilot ? { ...autopilot, linkedJobs: linkedJobsForLane(autopilot.id) } : autopilot;
+    const ralphWithJobs = ralph ? { ...ralph, linkedJobs: linkedJobsForLane(ralph.id) } : ralph;
+    const ultraworkWithJobs = ultrawork ? { ...ultrawork, linkedJobs: linkedJobsForLane(ultrawork.id) } : ultrawork;
+    return {
+        view,
+        staleCounts,
+        session,
+        autopilot: autopilotWithJobs,
+        ultrawork: ultraworkWithJobs,
+        ralph: ralphWithJobs,
+        activeOperator: operatorActive,
+        inbox: { open: openItems.length, total: inbox.length, recentOpen },
+        activeTasks,
+        team,
+        recentReviews,
+        goalScope,
+        unresolvedContractGaps: [],
+        phaseStale,
+        activeJobs: {
+            scheduled: scheduledJobs.length,
+            paused: pausedJobs.length,
+            monitors: monitorJobs.length,
+            nextFireAt,
+        },
+        continuation,
+        logicalIdle,
+        stopSafety: (() => {
+            const verdict = evaluateStopPolicy({ authority, root: authority.root });
+            return {
+                outcome: verdict.outcome,
+                reasons: verdict.reasons,
+                transportCanBlock: verdict.transportCanBlock,
+            };
+        })(),
+    };
+}
+export const workflowToolDefinitions = [
+    {
+        name: 'operator_workflow_reconcile',
+        description: 'Classify stale workflow state in tasks/reviews and optionally stamp additive metadata hints. Does not delete records or advance phases.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+                apply: {
+                    type: 'boolean',
+                    description: 'Apply additive metadata updates (reviewStale/task.reviewStale) for detected stale pairs.',
+                },
+                staleReviewAgeMs: {
+                    type: 'number',
+                    description: `If a pending review is this many milliseconds old, classify as stale. Defaults to ${DEFAULT_REVIEW_STALE_MS}.`,
+                },
+            },
+        },
+    },
+    {
+        name: 'operator_resume_from_repo_truth',
+        description: 'D8 re-open helper: refresh stale flags via reconcile, then compose D4/D5 recompute if those tools are present. Returns consolidated { reconciled, recomputed, reassessed, suggestedNextActions[] }. Does NOT advance any state beyond what D4 already permits.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+                modeType: { type: 'string', enum: ['ralph', 'ultrawork', 'autopilot'], description: 'Runtime mode type.' },
+                modeId: { type: 'string', description: 'Optional mode id; if omitted reads current session.' },
+            },
+        },
+    },
+    {
+        name: 'operator_review_refresh',
+        description: 'D8 re-open helper: re-run computeReviewStaleState for one review against the current ledger verification runs and update staleState/supersededBy if changed. Returns { before, after, changed }.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+                reviewId: { type: 'string', description: 'The review id to refresh.' },
+            },
+            required: ['reviewId'],
+        },
+    },
+    {
+        name: 'operator_task_reconcile',
+        description: 'D8 re-open helper: for a single runtime task (task), recompute reviewStale, blockerStale, evidenceOutdated from current ledger/repo truth and update additive companion metadata in place. Returns the delta.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+                taskId: { type: 'string', description: 'The local task id (runtime tool-id vocabulary).' },
+            },
+            required: ['taskId'],
+        },
+    },
+    {
+        name: 'operator_runtime_bootstrap_status',
+        description: 'Read-only check of the Operator runtime layout. Returns which required directories and seeded JSON files are present or missing under the .enact/operator tree.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+            },
+        },
+    },
+    {
+        name: 'operator_runtime_bootstrap_repair',
+        description: 'Ensure the Operator runtime layout exists by calling ensureLayout, then return a status report plus a list of directories and files that were created.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+            },
+        },
+    },
+    {
+        name: 'operator_contract_parity_run',
+        description: 'Run the contract-parity gate for a lane tracker id. Reads closure criteria from .enact/operator/manifest.yaml only. Fails in strict mode if no declarative source exists.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+                taskId: { type: 'string' },
+            },
+            required: ['taskId'],
+        },
+    },
+    {
+        name: 'operator_task_create_closure_pass',
+        description: 'Creates a closure-pass task linked to the active Ultrawork session. Computes write-scope union across linked tasks and assigns closureScope of "integration" or "repo-end-to-end" based on breadth.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+                title: { type: 'string' },
+                notes: { type: 'array', items: { type: 'string' } },
+            },
+        },
+    },
+    {
+        name: 'operator_ralph_reassess',
+        description: 'D5 — Reassess the current Ralph blocker against repo truth. Returns classification: still-blocked-same-reason | still-blocked-different-reason | no-longer-blocked-but-unverified | ready-for-verifying. Emits ReconcileEvent. NEVER auto-advances phase.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+                modeType: { type: 'string', enum: ['ralph'], description: 'Optional ralph mode type hint.' },
+                modeId: { type: 'string', description: 'Optional ralph id; if omitted reads current session.' },
+                currentCommitHash: { type: 'string', description: 'HEAD commit hash. If omitted, resolved from git.' },
+            },
+        },
+    },
+    {
+        name: 'operator_operator_snapshot',
+        description: 'Composite read: returns a single authoritative snapshot of all operator-relevant Operator state — session, autopilot, ultrawork, ralph, activeSkill, inbox summary, active tasks, team, recent reviews, goalScope, and unresolvedContractGaps placeholder. Recomputed fresh on every call. recentOpen is capped at 5 items and recentReviews at 10 items. Optional fields[] filter returns only specified top-level keys and rejects typos. view="converged" (default) filters superseded reviews; view="raw" shows every artifact on disk.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+                fields: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'If provided, only these top-level keys are included in the response.',
+                },
+                view: { type: 'string', enum: ['raw', 'converged'], description: 'raw=all artifacts on disk; converged=superseded items filtered out (default).' },
+            },
+        },
+    },
+    {
+        name: 'operator_goal_resume_or_start',
+        description: 'READ-ONLY decision tool: inspect current Operator session state and return whether to resume an active session (goal matches), start a new one, or retarget an existing one. Returns a decision, reason, matchedSession (if resuming), recommendedAction (tool + params to call next), and a full operator snapshot. Does not mutate state.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: { type: 'string' },
+                goal: { type: 'string', description: 'The intended goal for the session.' },
+                mode: {
+                    type: 'string',
+                    enum: ['ralph', 'ultrawork'],
+                    description: 'Preferred mode hint. If absent, defaults to ultrawork.',
+                },
+            },
+            required: ['goal'],
+        },
+    },
+];
+export async function handleWorkflowTool(name, context) {
+    const { root, args, invokeTool } = context;
+    switch (name) {
+        case 'operator_ralph_reassess': {
+            const ralph = getRalph(root);
+            if (!ralph) {
+                throw new Error('No Ralph state found. Start Ralph first.');
+            }
+            if (ralph.phase !== 'blocked') {
+                throw new Error(`operator_ralph_reassess: Ralph is in phase "${ralph.phase}" but reassessment only applies to blocked phase.`);
+            }
+            const providedHash = typeof args.currentCommitHash === 'string' ? args.currentCommitHash : null;
+            const currentHash = providedHash ?? createEvidenceHorizon(root).commitHash;
+            const blockedAtHash = ralph.evidenceHorizon?.commitHash ?? null;
+            const hasCommitAdvanced = blockedAtHash !== null && currentHash !== blockedAtHash && currentHash !== 'unknown';
+            const blockedAt = ralph.evidenceHorizon?.verificationRunTimestamp ?? ralph.updatedAt;
+            const recentEntries = listLedger(root, 200).filter((entry) => entry.kind === 'session' && (entry.action === 'ralph_gate_passed' || entry.action === 'ralph_gate_failed') && entry.createdAt > blockedAt);
+            const hasRecentVerification = recentEntries.length > 0;
+            const recentPassedGates = recentEntries
+                .filter((entry) => entry.action === 'ralph_gate_passed')
+                .map((entry) => typeof entry.metadata.gateId === 'string' ? entry.metadata.gateId : '');
+            const pendingOrFailedGates = ralph.verificationGates.filter((gate) => gate.status !== 'passed');
+            const allBlockerGatesNowPassed = pendingOrFailedGates.length > 0 && pendingOrFailedGates.every((gate) => recentPassedGates.includes(gate.id));
+            let classification;
+            let suggestedBlockerReason;
+            if (allBlockerGatesNowPassed) {
+                classification = 'ready-for-verifying';
+            }
+            else if (hasCommitAdvanced && hasRecentVerification) {
+                classification = 'still-blocked-different-reason';
+                suggestedBlockerReason = `Commit advanced from ${blockedAtHash ?? 'unknown'} to ${currentHash}; some gates still pending.`;
+            }
+            else if (hasCommitAdvanced && !hasRecentVerification) {
+                classification = 'no-longer-blocked-but-unverified';
+            }
+            else {
+                classification = 'still-blocked-same-reason';
+            }
+            const evidenceHorizon = createEvidenceHorizon(root);
+            const reconcileEvent = {
+                kind: 'reconcile',
+                action: 'reconcile_complete',
+                schemaVersion: 1,
+                correlationId: `reconcile_${randomUUID().slice(0, 12)}`,
+                modeType: 'ralph',
+                modeId: ralph.id,
+                evidenceHorizon,
+                staleEntities: [],
+                autoApplied: [],
+                requiresOperatorDecision: [{
+                        entityType: 'task',
+                        entityId: ralph.id,
+                        description: `Ralph reassess: ${classification}`,
+                    }],
+            };
+            appendLedger(root, {
+                kind: 'reconcile',
+                action: reconcileEvent.action,
+                detail: `Ralph reassess "${ralph.id}": ${classification}`,
+                metadata: reconcileEvent,
+            });
+            return handled({
+                modeType: 'ralph',
+                modeId: ralph.id,
+                classification,
+                currentPhase: ralph.phase,
+                blockerReason: ralph.blockerReason,
+                blockerCategory: ralph.blockerCategory,
+                suggestedBlockerReason,
+                suggestedAction: classification === 'ready-for-verifying'
+                    ? 'Call operator_ralph_advance with toPhase=verifying'
+                    : classification === 'no-longer-blocked-but-unverified'
+                        ? 'Run verification gates then call operator_ralph_reassess again'
+                        : classification === 'still-blocked-different-reason'
+                            ? 'Update blockerReason via operator_ralph_block with the new category'
+                            : 'Continue resolving the existing blocker',
+                evidenceHorizon,
+                hasCommitAdvanced,
+                currentCommitHash: currentHash,
+                blockedAtCommitHash: blockedAtHash,
+            });
+        }
+        case 'operator_workflow_reconcile': {
+            const apply = args.apply === true;
+            const rawAgeMs = Number(args.staleReviewAgeMs);
+            const staleReviewAgeMs = Number.isFinite(rawAgeMs) && rawAgeMs >= 0 ? rawAgeMs : DEFAULT_REVIEW_STALE_MS;
+            const authority = readOperatorAuthority(root);
+            let phaseStale = false;
+            const ultraworkForReconcile = authority.ultrawork;
+            if (ultraworkForReconcile && ultraworkForReconcile.active) {
+                const reconcileContext = buildUltraworkPhaseContext(ultraworkForReconcile, authority.reviews, root);
+                const reconcileInference = inferUltraworkPhase(reconcileContext);
+                phaseStale = reconcileInference.inferredPhase !== null
+                    && reconcileInference.inferredPhase !== ultraworkForReconcile.phase
+                    && !reconcileInference.blockedByTransitionGuard;
+            }
+            const ledgerEntries = listLedger(root, 500);
+            const verificationRuns = ledgerEntries
+                .filter((entry) => entry.kind === 'review' && entry.metadata?.runId != null)
+                .map((entry) => ({
+                runId: String(entry.metadata?.runId ?? entry.action),
+                runTimestamp: entry.createdAt,
+                commitHash: String(entry.metadata?.commitHash ?? ''),
+                gateResults: [
+                    ...((Array.isArray(entry.metadata?.passedGates) ? entry.metadata.passedGates : []).map((gateId) => ({ gateId, passed: true }))),
+                    ...((Array.isArray(entry.metadata?.failedGates) ? entry.metadata.failedGates : []).map((gateId) => ({ gateId, passed: false }))),
+                ],
+            }))
+                .filter((run) => run.commitHash !== '' && run.runId !== '')
+                .slice(-100);
+            const reconcileResult = reconcileWorkflowState(root, authority.tasks, authority.reviews, {
+                apply,
+                staleReviewAgeMs,
+                verificationRuns: verificationRuns.length > 0 ? verificationRuns : undefined,
+            });
+            return handled({ ...reconcileResult, phaseStale });
+        }
+        case 'operator_resume_from_repo_truth': {
+            const authority = readOperatorAuthority(root);
+            const modeId = typeof args.modeId === 'string'
+                ? args.modeId
+                : authority.autopilot?.id ?? authority.ralph?.id ?? authority.ultrawork?.id;
+            const reconciled = reconcileWorkflowState(root, authority.tasks, authority.reviews, {
+                apply: true,
+                modeType: args.modeType,
+                modeId,
+            });
+            let recomputed = null;
+            const hasD4 = ultraworkToolDefinitions.some((tool) => tool.name === 'operator_ultrawork_recompute_phase');
+            if (hasD4 && authority.ultrawork?.active && invokeTool) {
+                try {
+                    recomputed = await invokeTool('operator_ultrawork_recompute_phase', { root, apply: true });
+                }
+                catch {
+                    recomputed = { skipped: true, reason: 'D4 not available or failed' };
+                }
+            }
+            else {
+                recomputed = {
+                    skipped: true,
+                    reason: authority.ultrawork?.active
+                        ? hasD4
+                            ? 'invokeTool unavailable'
+                            : 'D4 not yet landed'
+                        : 'no active ultrawork',
+                };
+            }
+            let reassessed = null;
+            const hasD5 = workflowToolDefinitions.some((tool) => tool.name === 'operator_ralph_reassess');
+            if (hasD5 && authority.ralph?.active && invokeTool) {
+                try {
+                    reassessed = await invokeTool('operator_ralph_reassess', { root });
+                }
+                catch {
+                    reassessed = { skipped: true, reason: 'D5 not available or failed' };
+                }
+            }
+            else {
+                reassessed = {
+                    skipped: true,
+                    reason: authority.ralph?.active
+                        ? hasD5
+                            ? 'invokeTool unavailable'
+                            : 'D5 not yet landed'
+                        : 'no active ralph',
+                };
+            }
+            const suggestedNextActions = [];
+            if (reconciled.summary.reviewInvalidations > 0) {
+                suggestedNextActions.push('operator_review_refresh — one or more reviews have updated staleState');
+            }
+            if (authority.ultrawork?.active && !hasD4) {
+                suggestedNextActions.push('operator_ultrawork_recompute_phase — land D4 to enable phase recompute');
+            }
+            if (authority.ralph?.active && !hasD5) {
+                suggestedNextActions.push('operator_ralph_reassess — land D5 to enable block-reason reassessment');
+            }
+            return handled({ reconciled, recomputed, reassessed, suggestedNextActions });
+        }
+        case 'operator_review_refresh': {
+            const reviewId = requiredString(args.reviewId, 'operator_review_refresh: reviewId is required.');
+            const allReviews = listReviews(root);
+            const review = allReviews.find((candidate) => candidate.id === reviewId);
+            if (!review) {
+                throw new Error(`Review "${reviewId}" not found.`);
+            }
+            const verificationRuns = listLedger(root, Number.MAX_SAFE_INTEGER)
+                .filter((entry) => entry.kind === 'review' && typeof entry.metadata.runId === 'string')
+                .map((entry) => {
+                const metadata = entry.metadata;
+                return {
+                    runId: String(metadata.runId),
+                    runTimestamp: String(metadata.runTimestamp ?? entry.createdAt),
+                    commitHash: String(metadata.commitHash ?? ''),
+                    gateResults: Array.isArray(metadata.gateResults)
+                        ? metadata.gateResults
+                        : [],
+                };
+            });
+            const beforeStaleState = review.staleState;
+            const { staleState: newStaleState, trigger } = computeReviewStaleState(review, verificationRuns);
+            const supersededBy = newStaleState === 'superseded'
+                ? verificationRuns
+                    .filter((run) => run.runTimestamp > (review.evidenceHorizon?.verificationRunTimestamp ?? ''))
+                    .sort((a, b) => b.runTimestamp.localeCompare(a.runTimestamp))[0]?.runId
+                : undefined;
+            const changed = newStaleState !== beforeStaleState;
+            if (changed) {
+                updateReview(root, reviewId, { staleState: newStaleState, supersededBy });
+            }
+            return handled({
+                before: { staleState: beforeStaleState },
+                after: { staleState: newStaleState, supersededBy },
+                changed,
+                trigger,
+            });
+        }
+        case 'operator_task_reconcile': {
+            const taskId = requiredString(args.taskId, 'operator_task_reconcile: taskId is required.');
+            const task = getTask(root, taskId);
+            if (!task) {
+                throw new Error(`Task "${taskId}" not found.`);
+            }
+            const allReviews = listReviews(root);
+            const taskReviews = allReviews.filter((review) => review.taskId === task.externalId || review.taskId === task.id);
+            const reviewStale = taskReviews.some((review) => review.status === 'pending' && (review.staleState === 'stale' || review.staleState === 'superseded'));
+            const blockerStale = task.status === 'blocked' && task.blockers.length === 0;
+            const latestReconcile = listLedger(root, 50)
+                .filter((entry) => entry.kind === 'reconcile')
+                .sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0];
+            const evidenceOutdated = latestReconcile !== undefined && taskReviews.some((review) => {
+                const horizon = review.evidenceHorizon?.verificationRunTimestamp;
+                return horizon !== undefined && horizon < latestReconcile.createdAt;
+            });
+            const before = {
+                reviewStale: task.reviewStale,
+                blockerStale: task.blockerStale,
+                evidenceOutdated: task.evidenceOutdated,
+            };
+            const after = { reviewStale, blockerStale, evidenceOutdated };
+            const delta = {};
+            if (before.reviewStale !== after.reviewStale)
+                delta.reviewStale = after.reviewStale;
+            if (before.blockerStale !== after.blockerStale)
+                delta.blockerStale = after.blockerStale;
+            if (before.evidenceOutdated !== after.evidenceOutdated)
+                delta.evidenceOutdated = after.evidenceOutdated;
+            if (Object.keys(delta).length > 0) {
+                updateTask(root, task.id, delta);
+            }
+            return handled({ taskId, before, after, delta, changed: Object.keys(delta).length > 0 });
+        }
+        case 'operator_runtime_bootstrap_status':
+            return handled(bootstrapStatus(root));
+        case 'operator_runtime_bootstrap_repair': {
+            const before = snapshotPaths(root);
+            ensureLayout(root);
+            const after = snapshotPaths(root);
+            return handled({ ...bootstrapStatus(root), created: after.filter((path) => !before.includes(path)) });
+        }
+        case 'operator_contract_parity_run':
+            return handled(runContractParity(root, typeof args.taskId === 'string' ? args.taskId : ''));
+        case 'operator_task_create_closure_pass': {
+            const ultrawork = getUltrawork(root);
+            if (!ultrawork) {
+                throw new Error('No active Ultrawork session. Start an Ultrawork session first.');
+            }
+            if (!ultrawork.active) {
+                throw new Error(`Ultrawork session "${ultrawork.id}" is not active (phase="${ultrawork.phase}"). Cannot create closure pass.`);
+            }
+            const linkedTaskCount = ultrawork.childTasks.length + (ultrawork.taskId ? 1 : 0);
+            let closureScope;
+            if (linkedTaskCount >= 3) {
+                closureScope = 'repo-end-to-end';
+            }
+            else if (linkedTaskCount >= 1) {
+                closureScope = defaultClosureScope();
+            }
+            else {
+                closureScope = 'integration';
+            }
+            const title = typeof args.title === 'string' && args.title.trim()
+                ? args.title
+                : `Closure pass [${closureScope}] for ultrawork ${ultrawork.id}`;
+            const notes = Array.isArray(args.notes)
+                ? args.notes
+                : [`Auto-created for ultrawork ${ultrawork.id} (${linkedTaskCount} linked tasks)`];
+            const closureTask = createTask(root, {
+                title,
+                kind: 'closure-pass',
+                phase: 'integration',
+                priority: 'high',
+                notes,
+                metadata: {
+                    modeType: 'ultrawork',
+                    modeId: ultrawork.id,
+                    closureScope,
+                    linkedTaskCount,
+                },
+            });
+            updateTask(root, closureTask.id, { closureScope });
+            linkTaskRef(root, closureTask.id);
+            return handled({
+                task: { ...closureTask, closureScope },
+                closureScope,
+                modeType: 'ultrawork',
+                modeId: ultrawork.id,
+            });
+        }
+        case 'operator_operator_snapshot': {
+            const authority = readOperatorAuthority(root);
+            const snapshotView = args.view === 'raw' ? 'raw' : 'converged';
+            const snapshot = composeOperatorSnapshot(authority, snapshotView);
+            const fields = Array.isArray(args.fields) ? args.fields : null;
+            if (fields && fields.length > 0) {
+                const validFields = asSnapshotFieldSet();
+                const invalid = fields.filter((field) => !validFields.has(field));
+                if (invalid.length > 0) {
+                    throw new Error(`Unknown operator snapshot field(s): ${invalid.join(', ')}. Allowed fields: ${SNAPSHOT_FIELDS.join(', ')}.`);
+                }
+                const filtered = {};
+                for (const field of fields) {
+                    if (Object.prototype.hasOwnProperty.call(snapshot, field)) {
+                        filtered[field] = snapshot[field];
+                    }
+                }
+                return handled(filtered);
+            }
+            return handled(snapshot);
+        }
+        case 'operator_goal_resume_or_start': {
+            const goal = requiredString(normalizeOperatorGoal(String(args.goal ?? '')).trim(), 'operator_goal_resume_or_start: goal is required.');
+            const modeHint = typeof args.mode === 'string' && (args.mode === 'ralph' || args.mode === 'ultrawork')
+                ? args.mode
+                : 'ultrawork';
+            const authority = readOperatorAuthority(root);
+            const { ralph, ultrawork } = authority;
+            const snapshot = composeOperatorSnapshot(authority);
+            const activeUltrawork = ultrawork?.active ? ultrawork : null;
+            const activeRalph = ralph?.active ? ralph : null;
+            let decision;
+            let reason;
+            let matchedSession = null;
+            let recommendedAction = null;
+            const activeForMode = modeHint === 'ralph' ? activeRalph : activeUltrawork;
+            const currentGoal = activeGoalForMode(modeHint, activeRalph, activeUltrawork);
+            if (!activeForMode) {
+                decision = 'start';
+                reason = `No active ${modeHint} session found. Start one with goal "${goal}".`;
+                recommendedAction = {
+                    tool: modeHint === 'ralph' ? 'operator_ralph_start' : 'operator_ultrawork_start',
+                    params: modeHint === 'ralph' ? { goal } : { intent: goal },
+                };
+            }
+            else if (currentGoal !== null && currentGoal.trim() === goal) {
+                decision = 'resume';
+                reason = `Active ${modeHint} session already has goal "${goal}". Nothing to do.`;
+                matchedSession = {
+                    mode: modeHint,
+                    currentGoal,
+                    goalScope: activeForMode.goalScope ?? null,
+                };
+            }
+            else {
+                decision = 'retarget-needed';
+                reason = `Active ${modeHint} has goal "${currentGoal ?? ''}"; explicit retarget required.`;
+                recommendedAction = {
+                    tool: modeHint === 'ralph' ? 'operator_ralph_retarget' : 'operator_ultrawork_retarget',
+                    params: modeHint === 'ralph'
+                        ? { goal, mode: 'replace-intent' }
+                        : { intent: goal, mode: 'replace-intent' },
+                };
+            }
+            return handled({ decision, reason, matchedSession, recommendedAction, snapshot });
+        }
+        default:
+            return UNHANDLED;
+    }
+}
+//# sourceMappingURL=workflow.js.map