@amsterdamdatalabs/enact-operator 0.1.2

package/dist/lanes/ultrawork/index.js

@@ -0,0 +1,919 @@
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { ensureLayout, layoutPath, readJsonFile, validateJsonFile, writeJson, appendLedger, upsertInboxItem, goalScopeRank, assertLifecycleTransitionAllowed, buildLifecycleCore, lifecycleNow, recordLifecyclePhaseTransition, resolveLifecycleRetargetScopeAndProfile, resolveLifecycleStartScopeAndProfile, } from '../../operator/operatorRuntimeCore.js';
+import { clearContinuationState } from '../../shared/workflow/continuation/continuation.js';
+import { resolveOperatorRoot } from '../../shared/core/contract.js';
+import { readNotepad, renderNotepadContextSection } from '../../shared/workflow/planning/notepad.js';
+import { coalesceTaskId } from '../../shared/core/terminology.js';
+const ULTRAWORK_SCHEMA_VERSION = 1;
+const UltraworkVerificationSchema = z.object({
+    phase: z.enum(['clarify', 'plan', 'execute', 'verify', 'review', 'blocked', 'completed', 'aborted']),
+    evidence: z.string(),
+    recordedAt: z.string(),
+    closureScope: z.enum(['lane-local', 'integration', 'repo-end-to-end']).optional(),
+});
+const UltraworkHistoryEntrySchema = z.object({
+    phase: z.enum(['clarify', 'plan', 'execute', 'verify', 'review', 'blocked', 'completed', 'aborted']),
+    route: z.enum(['direct', 'deep-interview', 'plan-only', 'team-escalated']).optional(),
+    at: z.string(),
+    by: z.string().optional(),
+    note: z.string().optional(),
+    retargetEvent: z.object({
+        oldIntent: z.string(),
+        newIntent: z.string(),
+        retargetMode: z.enum(['replace-intent', 'narrow-scope', 'resume-unchanged', 'fork-child-task']),
+        preservedState: z.enum(['preserved', 'narrowed', 'replaced', 'forked']),
+        reason: z.string().optional(),
+    }).optional(),
+});
+const UltraworkActivationMetadataSchema = z.object({
+    rawMarker: z.string().optional(),
+    source: z.enum(['hook', 'cli', 'mcp']).optional(),
+    detectedAt: z.string().optional(),
+    originalGoal: z.string().optional(),
+}).catchall(z.unknown());
+const UltraworkStateSchema = z.object({
+    schemaVersion: z.literal(ULTRAWORK_SCHEMA_VERSION),
+    id: z.string(),
+    active: z.boolean(),
+    phase: z.enum(['clarify', 'plan', 'execute', 'verify', 'review', 'blocked', 'completed', 'aborted']),
+    route: z.enum(['direct', 'deep-interview', 'plan-only', 'team-escalated']),
+    intent: z.string(),
+    sessionId: z.string().optional(),
+    planId: z.string().optional(),
+    researchIds: z.array(z.string()),
+    taskIds: z.array(z.string()),
+    childTasks: z.array(z.object({
+        id: z.string(),
+        intent: z.string(),
+        createdAt: z.string(),
+        status: z.enum(['pending', 'completed', 'cancelled']),
+    })),
+    escalation: z.object({
+        active: z.boolean(),
+        teamId: z.string().optional(),
+        reason: z.string().optional(),
+        escalatedAt: z.string().optional(),
+    }),
+    verifications: z.array(UltraworkVerificationSchema),
+    blockerReason: z.string().optional(),
+    abortReason: z.string().optional(),
+    completionSummary: z.string().optional(),
+    history: z.array(UltraworkHistoryEntrySchema),
+    activationMetadata: UltraworkActivationMetadataSchema.optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    closureState: z.enum(['none', 'integration_pending', 'integration_approved', 'goal_closed']),
+    goalScope: z.enum(['repo-local', 'operator-runtime', 'operator-replacement']).optional(),
+    gateProfile: z.enum(['repo-delivery', 'operator-runtime', 'operator-replacement', 'benchmark-harness']).optional(),
+    taskId: z.string().optional(),
+    assignmentId: z.string().optional(),
+    subagents: z.array(z.object({
+        id: z.string(),
+        status: z.enum(['active', 'completed', 'failed', 'cancelled']),
+        startedAt: z.string(),
+        completedAt: z.string().optional(),
+        summary: z.string().optional(),
+    })),
+    scenarios: z.array(z.object({
+        class: z.enum(['happy', 'edge', 'regression']),
+        description: z.string(),
+        passCondition: z.string(),
+        surfaceArtifact: z.string(),
+    })).optional(),
+    scenarioContract: z.enum(['PASS', 'FAIL']).optional(),
+    reviewerGateTriggered: z.boolean().optional(),
+    reviewerVerdict: z.enum(['UNCONDITIONAL_APPROVE', 'looks good but requires minor cleanup']).optional(),
+});
+// ── Transition table ──────────────────────────────────────────────────────────
+export const ULTRAWORK_TRANSITIONS = {
+    clarify: ['plan', 'execute', 'aborted'],
+    plan: ['execute', 'review', 'aborted', 'blocked'],
+    execute: ['verify', 'blocked', 'review', 'aborted'],
+    verify: ['completed', 'review', 'blocked', 'aborted'],
+    review: ['completed', 'execute', 'blocked', 'aborted'],
+    blocked: ['clarify', 'plan', 'execute', 'aborted'],
+    completed: [],
+    aborted: [],
+};
+const VERIFICATION_PHASES = new Set(['plan', 'execute', 'verify', 'review']);
+const ESCALATION_PHASES = new Set(['plan', 'execute']);
+const COMPLETION_PHASES = new Set(['verify', 'review']);
+const TERMINAL_PHASES = new Set(['completed', 'aborted']);
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function now() {
+    return lifecycleNow();
+}
+function hasPendingChildTasks(state) {
+    return state.childTasks.some((task) => task.status === 'pending');
+}
+/** Phase-inference context from ultrawork state only (no tasks.json reads). */
+export function buildUltraworkPhaseContext(state, reviews, root = resolveOperatorRoot()) {
+    const children = state.childTasks;
+    const childIds = children.map((child) => child.id);
+    const activeTasks = children.filter((child) => child.status === 'pending').length;
+    const completedTasks = children.filter((child) => child.status === 'completed').length;
+    const assignmentRef = coalesceTaskId(state);
+    const linkedReviews = Array.from(new Map(reviews
+        .filter((review) => {
+        const reviewTaskId = coalesceTaskId(review);
+        return ((assignmentRef !== undefined && reviewTaskId === assignmentRef)
+            || childIds.includes(reviewTaskId ?? ''));
+    })
+        .map((review) => [review.id, review])).values());
+    const basisIds = childIds.length > 0
+        ? childIds
+        : assignmentRef
+            ? [assignmentRef]
+            : [];
+    const notepad = readNotepad('ultrawork', state.id, root);
+    return {
+        taskIds: basisIds,
+        activeTasks,
+        completedTasks,
+        verifications: state.verifications,
+        reviews: linkedReviews,
+        currentPhase: state.phase,
+        contextSection: renderNotepadContextSection(notepad),
+    };
+}
+function resolveCompletionClosureState(_root, state) {
+    if (state.closureState === 'integration_approved' || state.closureState === 'goal_closed') {
+        return { closureState: state.closureState, inferred: false };
+    }
+    if (state.closureState === 'integration_pending') {
+        throw new Error(`Cannot complete ultrawork "${state.id}": closureState is "integration_pending". Record final approval with operator_ultrawork_set_closure_state before completing.`);
+    }
+    if (state.route === 'team-escalated' || state.escalation.active) {
+        throw new Error(`Cannot complete ultrawork "${state.id}": route "${state.route}" still requires explicit closure approval. Set closureState to "integration_approved" or "goal_closed" before completing.`);
+    }
+    if (hasPendingChildTasks(state)) {
+        throw new Error(`Cannot complete ultrawork "${state.id}": closureState is "none" and there are pending child tasks. Complete or cancel them, or set closureState explicitly before completing.`);
+    }
+    return { closureState: 'goal_closed', inferred: true };
+}
+function cancelPendingChildTasksOnReplaceIntent(state) {
+    const cancelledIds = [];
+    const childTasks = state.childTasks.map((child) => {
+        if (child.status !== 'pending')
+            return child;
+        cancelledIds.push(child.id);
+        return { ...child, status: 'cancelled' };
+    });
+    return { childTasks, cancelledIds };
+}
+function ultraworkFile(root) {
+    return layoutPath(root, 'state', 'ultrawork.json');
+}
+function migrateUltraworkState(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('Ultrawork state must be an object.');
+    }
+    const state = raw;
+    const schemaVersion = typeof state.schemaVersion === 'number' ? state.schemaVersion : 0;
+    if (schemaVersion !== 0 && schemaVersion !== ULTRAWORK_SCHEMA_VERSION) {
+        throw new Error(`Unsupported Ultrawork schemaVersion ${schemaVersion}.`);
+    }
+    // Forward-fill new optional fields on old records
+    const goalScope = state.goalScope === 'repo-local'
+        || state.goalScope === 'operator-runtime'
+        || state.goalScope === 'operator-replacement'
+        ? state.goalScope
+        : undefined;
+    const gateProfile = state.gateProfile === 'repo-delivery'
+        || state.gateProfile === 'operator-runtime'
+        || state.gateProfile === 'operator-replacement'
+        || state.gateProfile === 'benchmark-harness'
+        ? state.gateProfile
+        : undefined;
+    const childTasks = Array.isArray(state.childTasks) ? state.childTasks : [];
+    const taskId = typeof state.taskId === 'string' ? state.taskId : undefined;
+    const assignmentId = typeof state.assignmentId === 'string' ? state.assignmentId : undefined;
+    const subagents = Array.isArray(state.subagents) ? state.subagents : [];
+    const scenarios = Array.isArray(state.scenarios) ? state.scenarios : [];
+    const scenarioContract = state.scenarioContract === 'PASS' || state.scenarioContract === 'FAIL'
+        ? state.scenarioContract
+        : undefined;
+    const reviewerGateTriggered = typeof state.reviewerGateTriggered === 'boolean'
+        ? state.reviewerGateTriggered
+        : undefined;
+    const reviewerVerdict = state.reviewerVerdict === 'UNCONDITIONAL_APPROVE' || state.reviewerVerdict === 'looks good but requires minor cleanup'
+        ? state.reviewerVerdict
+        : undefined;
+    return {
+        ...state,
+        schemaVersion: ULTRAWORK_SCHEMA_VERSION,
+        closureState: state.closureState === 'integration_pending'
+            || state.closureState === 'integration_approved'
+            || state.closureState === 'goal_closed'
+            || state.closureState === 'none'
+            ? state.closureState
+            : 'none',
+        goalScope,
+        gateProfile,
+        childTasks,
+        taskIds: Array.isArray(state.taskIds)
+            ? state.taskIds
+            : [],
+        taskId,
+        assignmentId,
+        subagents,
+        scenarios,
+        scenarioContract,
+        reviewerGateTriggered,
+        reviewerVerdict,
+    };
+}
+function load(root) {
+    const path = ultraworkFile(root);
+    let raw;
+    try {
+        raw = readJsonFile(path);
+    }
+    catch (err) {
+        console.warn(`[ultrawork] stale or corrupt state file at ${path}: ${err instanceof Error ? err.message : String(err)}, treating as no active ultrawork`);
+        return null;
+    }
+    if (raw === undefined) {
+        return null;
+    }
+    try {
+        return validateJsonFile(path, migrateUltraworkState(raw), UltraworkStateSchema);
+    }
+    catch (err) {
+        console.warn(`[ultrawork] stale or corrupt state file at ${path}: ${err instanceof Error ? err.message : String(err)}, treating as no active ultrawork`);
+        return null;
+    }
+}
+function save(root, state) {
+    const next = { ...state, schemaVersion: ULTRAWORK_SCHEMA_VERSION, updatedAt: now() };
+    writeJson(ultraworkFile(root), next);
+    return next;
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+export function startUltrawork(root, opts) {
+    ensureLayout(root);
+    const existing = load(root);
+    if (existing?.active) {
+        throw new Error(`Cannot start a new ultrawork session: session "${existing.id}" is already active (phase="${existing.phase}"). Abort or complete it first.`);
+    }
+    // ── Profile selection guard (D4) ─────────────────────────────────────────
+    const { resolvedProfile, resolvedScope } = resolveLifecycleStartScopeAndProfile(root, {
+        text: opts.intent,
+        explicitGoalScope: opts.goalScope,
+        explicitGateProfile: opts.gateProfile,
+        contextLabel: 'operator_ultrawork_start',
+        hint: "Supply gateProfile='operator-replacement' for Operator self-hosting work, or 'operator-runtime' for runtime health checks.",
+    });
+    const id = `ultrawork_${randomUUID().slice(0, 12)}`;
+    const route = opts.route ?? 'direct';
+    const timestamp = lifecycleNow();
+    const state = {
+        schemaVersion: ULTRAWORK_SCHEMA_VERSION,
+        ...buildLifecycleCore({
+            id,
+            phase: 'clarify',
+            history: [{ phase: 'clarify', route, at: timestamp }],
+            goalScope: resolvedScope,
+            gateProfile: resolvedProfile,
+        }),
+        route,
+        intent: opts.intent,
+        sessionId: opts.sessionId,
+        researchIds: [],
+        taskIds: [],
+        childTasks: [],
+        escalation: { active: false },
+        verifications: [],
+        scenarios: [],
+        closureState: 'none',
+        activationMetadata: opts.activationMetadata,
+        taskId: opts.taskId,
+        assignmentId: opts.assignmentId,
+        subagents: [],
+    };
+    const bootstrappedState = save(root, state);
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_start',
+        detail: `Started ultrawork "${id}" with intent: ${opts.intent}`,
+        metadata: { id, route, phase: 'clarify' },
+    });
+    upsertInboxItem(root, {
+        kind: 'system',
+        subject: 'Ultrawork session started',
+        body: `Session "${id}" initiated in phase=clarify route=${route}`,
+        status: 'open',
+    });
+    clearContinuationState(root, 'ultrawork started', 'operator_ultrawork_start');
+    return bootstrappedState;
+}
+export function getUltrawork(root) {
+    return load(root);
+}
+export function routeUltrawork(root, route, note) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot route ultrawork: no ultrawork state file found.');
+    }
+    if (TERMINAL_PHASES.has(state.phase)) {
+        throw new Error(`Cannot re-route ultrawork "${state.id}": session is in terminal phase="${state.phase}".`);
+    }
+    const entry = { phase: state.phase, route, at: now(), note };
+    const next = save(root, {
+        ...state,
+        route,
+        history: [...state.history, entry],
+    });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_route',
+        detail: `Re-routed ultrawork "${state.id}" to route=${route}`,
+        metadata: { id: state.id, route, phase: state.phase },
+    });
+    clearContinuationState(root, `ultrawork routed to ${route}`, 'operator_ultrawork_route');
+    return next;
+}
+export function advanceUltrawork(root, opts) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot advance ultrawork: no ultrawork state file found.');
+    }
+    if (opts.toPhase === 'aborted') {
+        throw new Error(`Cannot advance to "aborted" via advanceUltrawork. Use abortUltrawork() instead.`);
+    }
+    const allowed = ULTRAWORK_TRANSITIONS[state.phase];
+    if (allowed.length === 0) {
+        throw new Error(`Cannot advance ultrawork "${state.id}": phase="${state.phase}" is terminal with no allowed transitions.`);
+    }
+    assertLifecycleTransitionAllowed('ultrawork', state.id, state.phase, opts.toPhase, ULTRAWORK_TRANSITIONS);
+    const entry = {
+        phase: opts.toPhase,
+        route: state.route,
+        at: lifecycleNow(),
+        by: opts.by,
+        note: opts.note,
+    };
+    const next = save(root, {
+        ...state,
+        phase: opts.toPhase,
+        history: [...state.history, entry],
+    });
+    recordLifecyclePhaseTransition(root, {
+        modeType: 'ultrawork',
+        laneId: state.id,
+        fromPhase: state.phase,
+        toPhase: opts.toPhase,
+        trigger: opts.trigger,
+        sessionAction: 'ultrawork_advance',
+        sessionDetail: `Advanced ultrawork "${state.id}" from "${state.phase}" to "${opts.toPhase}"`,
+        sessionMetadata: { id: state.id, from: state.phase, to: opts.toPhase, by: opts.by },
+        actor: opts.by,
+        sessionId: state.sessionId,
+        runId: state.taskId ?? state.id,
+    });
+    clearContinuationState(root, `ultrawork advanced to ${opts.toPhase}`, 'operator_ultrawork_advance');
+    return next;
+}
+export function escalateToTeam(root, teamId, reason) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot escalate: no ultrawork state file found.');
+    }
+    if (!ESCALATION_PHASES.has(state.phase)) {
+        throw new Error(`Cannot escalate ultrawork "${state.id}" to team: escalation is only allowed from phases [${[...ESCALATION_PHASES].join(', ')}], but current phase is "${state.phase}".`);
+    }
+    const timestamp = now();
+    const entry = {
+        phase: state.phase,
+        route: 'team-escalated',
+        at: timestamp,
+        note: `Escalated to team "${teamId}": ${reason}`,
+    };
+    const next = save(root, {
+        ...state,
+        route: 'team-escalated',
+        escalation: { active: true, teamId, reason, escalatedAt: timestamp },
+        history: [...state.history, entry],
+    });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_escalate',
+        detail: `Escalated ultrawork "${state.id}" to team "${teamId}": ${reason}`,
+        metadata: { id: state.id, teamId, reason, phase: state.phase },
+    });
+    return next;
+}
+export function recordUltraworkVerification(root, evidence, options = {}) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot record verification: no ultrawork state file found.');
+    }
+    if (!VERIFICATION_PHASES.has(state.phase)) {
+        throw new Error(`Cannot record verification for ultrawork "${state.id}": verification is only allowed in phases [${[...VERIFICATION_PHASES].join(', ')}], but current phase is "${state.phase}".`);
+    }
+    const verification = {
+        phase: state.phase,
+        evidence,
+        recordedAt: now(),
+    };
+    let scenarios = state.scenarios;
+    let scenarioContract = state.scenarioContract;
+    if (options.scenarios !== undefined) {
+        const invalid = options.scenarios.find((scenario) => scenario.description.trim() === ''
+            || scenario.passCondition.trim() === ''
+            || scenario.surfaceArtifact.trim() === '');
+        if (invalid) {
+            throw new Error(`Invalid ultrawork scenario contract: scenario "${invalid.class}" must include non-empty description, passCondition, and surfaceArtifact.`);
+        }
+        const requiredClasses = ['happy', 'edge', 'regression'];
+        const present = new Set(options.scenarios.map((scenario) => scenario.class));
+        const missing = requiredClasses.filter((klass) => !present.has(klass));
+        if (missing.length > 0) {
+            throw new Error(`Invalid ultrawork scenario contract: missing scenario class: ${missing[0]}.`);
+        }
+        scenarios = options.scenarios;
+        scenarioContract = 'PASS';
+    }
+    const reviewerGateTriggered = shouldTriggerReviewerGate(root, state);
+    const reviewerVerdict = options.reviewerVerdict ?? state.reviewerVerdict;
+    const next = save(root, {
+        ...state,
+        verifications: [...state.verifications, verification],
+        scenarios,
+        scenarioContract,
+        reviewerGateTriggered,
+        reviewerVerdict,
+    });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_verification',
+        detail: `Recorded verification evidence for ultrawork "${state.id}" in phase="${state.phase}"`,
+        metadata: { id: state.id, phase: state.phase },
+    });
+    clearContinuationState(root, 'ultrawork verification recorded', 'operator_ultrawork_verify');
+    return next;
+}
+export function linkPlan(root, planId) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot link plan: no ultrawork state file found.');
+    }
+    const next = save(root, { ...state, planId });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_link_plan',
+        detail: `Linked plan "${planId}" to ultrawork "${state.id}"`,
+        metadata: { id: state.id, planId },
+    });
+    return next;
+}
+export function linkTaskRef(root, taskId) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot link task ref: no ultrawork state file found.');
+    }
+    if (state.taskIds.includes(taskId)) {
+        return state;
+    }
+    const next = save(root, { ...state, taskIds: [...state.taskIds, taskId] });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_link_task',
+        detail: `Linked task ref "${taskId}" to ultrawork "${state.id}"`,
+        metadata: { id: state.id, taskId },
+    });
+    return next;
+}
+export function retargetUltrawork(root, opts) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot retarget ultrawork: no ultrawork state file found.');
+    }
+    if (TERMINAL_PHASES.has(state.phase)) {
+        throw new Error(`Cannot retarget ultrawork "${state.id}": session is in terminal phase="${state.phase}".`);
+    }
+    const { resolvedProfile, resolvedScope } = resolveLifecycleRetargetScopeAndProfile(root, {
+        text: opts.intent,
+        explicitGoalScope: opts.goalScope,
+        explicitGateProfile: opts.gateProfile,
+        currentGoalScope: state.goalScope,
+        currentGateProfile: state.gateProfile,
+        contextLabel: 'operator_ultrawork_retarget',
+    });
+    if (state.goalScope && resolvedScope && goalScopeRank(resolvedScope) > goalScopeRank(state.goalScope)) {
+        throw new Error(`Cannot retarget ultrawork "${state.id}": requested scope "${resolvedScope}" would broaden active scope "${state.goalScope}". Start a new session instead.`);
+    }
+    const event = {
+        oldIntent: state.intent,
+        newIntent: opts.intent,
+        retargetMode: opts.mode,
+        preservedState: opts.mode === 'resume-unchanged'
+            ? 'preserved'
+            : opts.mode === 'narrow-scope'
+                ? 'narrowed'
+                : opts.mode === 'fork-child-task'
+                    ? 'forked'
+                    : 'replaced',
+        reason: opts.note ?? `Retargeted intent from "${state.intent}" to "${opts.intent}".`,
+    };
+    const { childTasks: retargetChildTasks, cancelledIds } = opts.mode === 'replace-intent'
+        ? cancelPendingChildTasksOnReplaceIntent(state)
+        : { childTasks: state.childTasks, cancelledIds: [] };
+    if (cancelledIds.length > 0) {
+        event.reason = `${event.reason} Cancelled pending child tasks: ${cancelledIds.join(', ')}`;
+    }
+    if (opts.mode === 'resume-unchanged') {
+        const entry = {
+            phase: state.phase,
+            route: state.route,
+            at: now(),
+            by: opts.by,
+            note: opts.note ?? 'Retarget decision: resume unchanged.',
+            retargetEvent: event,
+        };
+        return save(root, { ...state, history: [...state.history, entry] });
+    }
+    if (opts.mode === 'fork-child-task') {
+        if (state.scenarioContract !== 'PASS') {
+            throw new Error(`Cannot dispatch a child task for ultrawork "${state.id}": missing scenario contract. Call operator_ultrawork_verify with happy, edge, and regression scenarios first.`);
+        }
+        const childTask = {
+            id: `child_${randomUUID().slice(0, 12)}`,
+            intent: opts.intent,
+            createdAt: now(),
+            status: 'pending',
+        };
+        const entry = {
+            phase: state.phase,
+            route: state.route,
+            at: childTask.createdAt,
+            by: opts.by,
+            note: opts.note ?? `Forked child task ${childTask.id}`,
+            retargetEvent: event,
+        };
+        const next = save(root, {
+            ...state,
+            childTasks: [...state.childTasks, childTask],
+            history: [...state.history, entry],
+        });
+        appendLedger(root, {
+            kind: 'session',
+            action: 'ultrawork_retarget_fork_child',
+            detail: `Forked child task "${childTask.id}" from ultrawork "${state.id}"`,
+            metadata: { id: state.id, childTaskId: childTask.id },
+        });
+        return next;
+    }
+    const entry = {
+        phase: state.phase,
+        route: state.route,
+        at: now(),
+        by: opts.by,
+        note: opts.note ?? `Retargeted intent from "${state.intent}" to "${opts.intent}"`,
+        retargetEvent: event,
+    };
+    const next = save(root, {
+        ...state,
+        intent: opts.intent,
+        goalScope: resolvedScope,
+        gateProfile: resolvedProfile,
+        childTasks: retargetChildTasks,
+        history: [...state.history, entry],
+    });
+    for (const childTaskId of cancelledIds) {
+        appendLedger(root, {
+            kind: 'session',
+            action: 'ultrawork_retarget_child_cancelled',
+            detail: `Cancelled child task "${childTaskId}" by replace-intent retarget on ultrawork "${state.id}"`,
+            metadata: { modeType: 'ultrawork', modeId: state.id, childTaskId, fromIntent: state.intent, toIntent: opts.intent },
+        });
+    }
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_retarget',
+        detail: `Retargeted ultrawork "${state.id}" via ${opts.mode}`,
+        metadata: { id: state.id, mode: opts.mode, goalScope: resolvedScope, gateProfile: resolvedProfile },
+    });
+    clearContinuationState(root, `ultrawork retargeted via ${opts.mode}`, 'operator_ultrawork_retarget');
+    return next;
+}
+export function completeUltraworkChildTask(root, childTaskId, opts) {
+    return setUltraworkChildTaskStatus(root, childTaskId, 'completed', opts);
+}
+export function cancelUltraworkChildTask(root, childTaskId, opts) {
+    return setUltraworkChildTaskStatus(root, childTaskId, 'cancelled', opts);
+}
+function setUltraworkChildTaskStatus(root, childTaskId, status, opts) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot update ultrawork child task state: no ultrawork state file found.');
+    }
+    const index = state.childTasks.findIndex((task) => task.id === childTaskId);
+    if (index === -1) {
+        throw new Error(`No ultrawork child task found with id "${childTaskId}".`);
+    }
+    const existing = state.childTasks[index];
+    if (existing.status !== 'pending') {
+        throw new Error(`Cannot set ultrawork child task "${childTaskId}" to ${status}; current status is "${existing.status}".`);
+    }
+    const note = opts?.note ?? `${status === 'completed' ? 'Completed' : 'Cancelled'} child task "${childTaskId}"`;
+    const completedAt = now();
+    const nextChildTask = { ...existing, status };
+    const nextChildTasks = [...state.childTasks];
+    nextChildTasks[index] = nextChildTask;
+    const entry = {
+        phase: state.phase,
+        route: state.route,
+        at: completedAt,
+        by: opts?.by,
+        note,
+        retargetEvent: {
+            oldIntent: state.intent,
+            newIntent: state.intent,
+            retargetMode: 'resume-unchanged',
+            preservedState: 'preserved',
+            reason: note,
+        },
+    };
+    const next = save(root, {
+        ...state,
+        childTasks: nextChildTasks,
+        history: [...state.history, entry],
+    });
+    appendLedger(root, {
+        kind: 'session',
+        action: status === 'completed' ? 'ultrawork_child_task_complete' : 'ultrawork_child_task_cancel',
+        detail: `${note} in ultrawork "${state.id}"`,
+        metadata: { id: state.id, childTaskId },
+    });
+    return next;
+}
+export function linkResearch(root, researchId) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot link research: no ultrawork state file found.');
+    }
+    if (state.researchIds.includes(researchId)) {
+        return state;
+    }
+    const next = save(root, { ...state, researchIds: [...state.researchIds, researchId] });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_link_research',
+        detail: `Linked research "${researchId}" to ultrawork "${state.id}"`,
+        metadata: { id: state.id, researchId },
+    });
+    return next;
+}
+export function completeUltrawork(root, summary) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot complete ultrawork: no ultrawork state file found.');
+    }
+    if (!COMPLETION_PHASES.has(state.phase)) {
+        throw new Error(`Cannot complete ultrawork "${state.id}": completion requires phase ∈ [${[...COMPLETION_PHASES].join(', ')}], but current phase is "${state.phase}".`);
+    }
+    if (state.verifications.length === 0) {
+        throw new Error(`Cannot complete ultrawork "${state.id}": at least one verification evidence record is required before completion.`);
+    }
+    const refreshedReviewerGateTriggered = shouldTriggerReviewerGate(root, state);
+    const gateState = refreshedReviewerGateTriggered === state.reviewerGateTriggered
+        ? state
+        : save(root, {
+            ...state,
+            reviewerGateTriggered: refreshedReviewerGateTriggered,
+        });
+    if (gateState.reviewerGateTriggered === true
+        && gateState.reviewerVerdict !== 'UNCONDITIONAL_APPROVE') {
+        throw new Error(`Cannot complete ultrawork "${gateState.id}": reviewer gate triggered and reviewerVerdict is not UNCONDITIONAL_APPROVE.`);
+    }
+    const completionClosure = resolveCompletionClosureState(root, gateState);
+    const entry = {
+        phase: 'completed',
+        route: gateState.route,
+        at: now(),
+        note: summary,
+    };
+    const next = save(root, {
+        ...gateState,
+        phase: 'completed',
+        active: false,
+        closureState: completionClosure.closureState,
+        completionSummary: summary,
+        history: [...state.history, entry],
+    });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_complete',
+        detail: `Completed ultrawork "${state.id}": ${summary}`,
+        metadata: {
+            id: state.id,
+            closureState: completionClosure.closureState,
+            closureStateSource: completionClosure.inferred ? 'inferred' : 'explicit',
+        },
+    });
+    upsertInboxItem(root, {
+        kind: 'system',
+        subject: 'Ultrawork session completed',
+        body: `Session "${state.id}" completed. Summary: ${summary}`,
+        status: 'open',
+    });
+    return next;
+}
+function countChangedFiles(root) {
+    try {
+        const output = execFileSync('git', ['-C', root, 'diff', '--name-only', 'HEAD'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return output
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .length;
+    }
+    catch {
+        return 0;
+    }
+}
+function shouldTriggerReviewerGate(root, state) {
+    if (state.reviewerGateTriggered === true) {
+        return true;
+    }
+    const changedFiles = countChangedFiles(root);
+    const riskyIntent = /\b(refactor|migration|migrate|perf|performance|security)\b/i.test(state.intent);
+    return changedFiles >= 3 || riskyIntent;
+}
+export function blockUltrawork(root, reason) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot block ultrawork: no ultrawork state file found.');
+    }
+    if (TERMINAL_PHASES.has(state.phase)) {
+        throw new Error(`Cannot block ultrawork "${state.id}": session is already in terminal phase="${state.phase}".`);
+    }
+    const entry = {
+        phase: 'blocked',
+        route: state.route,
+        at: now(),
+        note: reason,
+    };
+    const next = save(root, {
+        ...state,
+        phase: 'blocked',
+        blockerReason: reason,
+        history: [...state.history, entry],
+    });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_block',
+        detail: `Blocked ultrawork "${state.id}": ${reason}`,
+        metadata: { id: state.id, reason },
+    });
+    clearContinuationState(root, reason, 'operator_ultrawork_block');
+    return next;
+}
+export function abortUltrawork(root, reason) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot abort ultrawork: no ultrawork state file found.');
+    }
+    if (TERMINAL_PHASES.has(state.phase)) {
+        throw new Error(`Cannot abort ultrawork "${state.id}": session is already in terminal phase="${state.phase}".`);
+    }
+    const entry = {
+        phase: 'aborted',
+        route: state.route,
+        at: now(),
+        note: reason,
+    };
+    const next = save(root, {
+        ...state,
+        phase: 'aborted',
+        active: false,
+        abortReason: reason,
+        history: [...state.history, entry],
+    });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_abort',
+        detail: `Aborted ultrawork "${state.id}": ${reason}`,
+        metadata: { id: state.id, reason },
+    });
+    upsertInboxItem(root, {
+        kind: 'system',
+        subject: 'Ultrawork session aborted',
+        body: `Session "${state.id}" aborted. Reason: ${reason}`,
+        status: 'open',
+    });
+    clearContinuationState(root, reason, 'operator_ultrawork_abort');
+    return next;
+}
+export function setUltraworkClosureState(root, closureState, note) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot set closure state: no ultrawork state file found.');
+    }
+    if (TERMINAL_PHASES.has(state.phase)) {
+        throw new Error(`Cannot set closure state on ultrawork "${state.id}": session is in terminal phase="${state.phase}".`);
+    }
+    const next = save(root, { ...state, closureState });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_closure_state',
+        detail: `Set closureState="${closureState}" on ultrawork "${state.id}"${note ? ': ' + note : ''}`,
+        metadata: { id: state.id, closureState },
+    });
+    return next;
+}
+// ── Phase 8 — AzDo task link helpers ────────────────────────────────────────
+export function linkUltraworkTask(root, taskId) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ultrawork state found. Start Ultrawork first.');
+    }
+    if (state.taskId && state.taskId !== taskId) {
+        throw new Error(`Ultrawork "${state.id}" already linked to "${state.taskId}". ` +
+            `Call unlinkUltraworkTask first to retarget.`);
+    }
+    const next = save(root, { ...state, taskId });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_link_task',
+        detail: `Ultrawork "${state.id}" linked to task "${taskId}"`,
+        metadata: { modeType: 'ultrawork', modeId: state.id, taskId },
+    });
+    return next;
+}
+export function linkUltraworkAssignment(root, assignmentId) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ultrawork state found. Start Ultrawork first.');
+    }
+    if (state.assignmentId && state.assignmentId !== assignmentId) {
+        throw new Error(`Ultrawork "${state.id}" already linked to assignment "${state.assignmentId}". ` +
+            'Call unlinkUltraworkAssignment first to retarget.');
+    }
+    const next = save(root, { ...state, assignmentId });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_link_assignment',
+        detail: `Ultrawork "${state.id}" linked to assignment "${assignmentId}"`,
+        metadata: { modeType: 'ultrawork', modeId: state.id, assignmentId },
+    });
+    return next;
+}
+export function unlinkUltraworkTask(root) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ultrawork state found. Start Ultrawork first.');
+    }
+    const previous = state.taskId;
+    const { taskId: _removed, ...rest } = state;
+    void _removed;
+    const next = save(root, rest);
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_unlink_task',
+        detail: `Ultrawork "${state.id}" unlinked from task "${previous ?? 'none'}"`,
+        metadata: { modeType: 'ultrawork', modeId: state.id, previousTaskId: previous ?? null },
+    });
+    return next;
+}
+export function unlinkUltraworkAssignment(root) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ultrawork state found. Start Ultrawork first.');
+    }
+    const previous = state.assignmentId;
+    const { assignmentId: _removed, ...rest } = state;
+    void _removed;
+    const next = save(root, rest);
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ultrawork_unlink_assignment',
+        detail: `Ultrawork "${state.id}" unlinked from assignment "${previous ?? 'none'}"`,
+        metadata: { modeType: 'ultrawork', modeId: state.id, previousAssignmentId: previous ?? null },
+    });
+    return next;
+}
+//# sourceMappingURL=index.js.map