@amsterdamdatalabs/enact-operator 0.1.2

package/dist/lanes/ralph/index.js

@@ -0,0 +1,680 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { z } from 'zod';
+import { ensureLayout, layoutPath, readJsonFile, validateJsonFile, writeJson, appendLedger, upsertInboxItem, createEvidenceHorizon, defaultGoalScopeForRoot, goalScopeRank, resolveGateProfile, createLaneTrackerTask, syncLaneTrackerTasks, assertLifecycleTransitionAllowed, buildLifecycleCore, lifecycleNow, recordLifecyclePhaseTransition, resolveLifecycleRetargetScopeAndProfile, resolveLifecycleStartScopeAndProfile, } from '../../operator/operatorRuntimeCore.js';
+import { clearContinuationState } from '../../shared/workflow/continuation/continuation.js';
+const RALPH_SCHEMA_VERSION = 1;
+const DEFAULT_GATES = [
+    { id: 'doctor', name: 'Operator doctor' },
+    { id: 'tests', name: 'Real tests' },
+    { id: 'contract-parity', name: 'Contract-parity audit' },
+];
+const RalphVerificationGateSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    status: z.enum(['pending', 'passed', 'failed']),
+    evidence: z.string().optional(),
+    ranAt: z.string().optional(),
+});
+const RalphHistoryEntrySchema = z.object({
+    phase: z.enum(['idle', 'running', 'verifying', 'blocked', 'completed', 'aborted']),
+    at: z.string(),
+    by: z.string().optional(),
+    note: z.string().optional(),
+    retargetEvent: z.object({
+        oldGoal: z.string(),
+        newGoal: z.string(),
+        retargetMode: z.enum(['replace-intent', 'narrow-scope', 'resume-unchanged']),
+        preservedState: z.enum(['preserved', 'narrowed', 'replaced', 'forked']),
+        reason: z.string().optional(),
+    }).optional(),
+});
+const RalphActivationMetadataSchema = 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 EvidenceHorizonSchema = z.object({
+    commitHash: z.string(),
+    verificationRunId: z.string(),
+    verificationRunTimestamp: z.string(),
+    sessionSequence: z.number(),
+});
+const ArchitectVerdictSchema = z.object({
+    verdict: z.enum(['GO', 'NO-GO']),
+    reasons: z.array(z.string()),
+    evidencePointers: z.array(z.string()),
+});
+const RalphStateSchema = z.object({
+    schemaVersion: z.literal(RALPH_SCHEMA_VERSION),
+    id: z.string(),
+    active: z.boolean(),
+    phase: z.enum(['idle', 'running', 'verifying', 'blocked', 'completed', 'aborted']),
+    goal: z.string(),
+    sessionId: z.string().optional(),
+    taskIds: z.array(z.string()),
+    verificationGates: z.array(RalphVerificationGateSchema),
+    blockerReason: z.string().optional(),
+    blockerCategory: z.enum(['code-local', 'dependency-local', 'workflow-state-local', 'governance-platform-global']).optional(),
+    abortReason: z.string().optional(),
+    completionSummary: z.string().optional(),
+    history: z.array(RalphHistoryEntrySchema),
+    activationMetadata: RalphActivationMetadataSchema.optional(),
+    goalScope: z.enum(['repo-local', 'operator-runtime', 'operator-replacement']).optional(),
+    gateProfile: z.enum(['repo-delivery', 'operator-runtime', 'operator-replacement', 'benchmark-harness']).optional(),
+    linkedUltraworkId: z.string().optional(),
+    taskId: z.string().optional(),
+    evidenceHorizon: EvidenceHorizonSchema.optional(),
+    architectVerdict: ArchitectVerdictSchema.optional(),
+    architectLoop: z.boolean().optional(),
+    scopeFidelity: z.enum(['PASS', 'FAIL']).optional(),
+    scopeViolations: z.array(z.string()).optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+const VALID_TRANSITIONS = {
+    idle: ['running'],
+    running: ['verifying', 'blocked', 'aborted'],
+    verifying: ['running', 'completed', 'blocked', 'aborted'],
+    blocked: ['running', 'aborted'],
+    completed: [],
+    aborted: [],
+};
+function defaultClosureScopeForGoalScope(scope) {
+    if (scope === 'operator-replacement')
+        return 'repo-end-to-end';
+    if (scope === 'operator-runtime')
+        return 'lane-local';
+    return 'integration';
+}
+function trackerStatusForRalphPhase(phase) {
+    switch (phase) {
+        case 'running':
+            return 'in_progress';
+        case 'verifying':
+            return 'review';
+        case 'blocked':
+            return 'blocked';
+        case 'completed':
+            return 'completed';
+        case 'aborted':
+            return 'cancelled';
+        default:
+            return null;
+    }
+}
+function ralphFile(root) {
+    return layoutPath(root, 'state', 'ralph.json');
+}
+function closureManifestFile(root) {
+    return layoutPath(root, 'state', 'closure-manifest.json');
+}
+const RALPH_WORKING_HEADERS = [
+    '## Confirmed Requirements',
+    '## Technical Decisions',
+    '## Research Findings',
+    '## Open Questions',
+    '## Scope Boundaries',
+];
+function ralphSessionWorkingFile(root, sessionId) {
+    return layoutPath(root, 'ralph', sessionId, 'working.md');
+}
+function ralphLiveWorkingFile(root) {
+    return layoutPath(root, 'state', 'ralph-working.md');
+}
+function buildInitialRalphWorkingMemory() {
+    return `${RALPH_WORKING_HEADERS.join('\n\n')}\n`;
+}
+function ensureWorkingFile(path) {
+    if (existsSync(path))
+        return;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, buildInitialRalphWorkingMemory(), 'utf8');
+}
+function appendTimestampedSectionEntry(path, section, entry) {
+    ensureWorkingFile(path);
+    const raw = readFileSync(path, 'utf8');
+    const lines = raw.split('\n');
+    const sectionIndex = lines.findIndex((line) => line.trim() === section);
+    if (sectionIndex < 0)
+        return;
+    let endIndex = lines.length;
+    for (let i = sectionIndex + 1; i < lines.length; i += 1) {
+        if (RALPH_WORKING_HEADERS.includes(lines[i].trim())) {
+            endIndex = i;
+            break;
+        }
+    }
+    const timestamped = `- [${now()}] ${entry}`;
+    lines.splice(endIndex, 0, timestamped);
+    writeFileSync(path, `${lines.join('\n').replace(/\n*$/, '\n')}`, 'utf8');
+}
+function appendRalphWorkingMemoryEntry(root, state, section, entry) {
+    const sessionId = state.sessionId ?? state.id;
+    const livePath = ralphLiveWorkingFile(root);
+    const sessionPath = ralphSessionWorkingFile(root, sessionId);
+    appendTimestampedSectionEntry(livePath, section, entry);
+    appendTimestampedSectionEntry(sessionPath, section, entry);
+}
+function now() {
+    return lifecycleNow();
+}
+function migrateRalphState(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('Ralph state must be an object.');
+    }
+    const state = raw;
+    const schemaVersion = typeof state.schemaVersion === 'number' ? state.schemaVersion : 0;
+    if (schemaVersion !== 0 && schemaVersion !== RALPH_SCHEMA_VERSION) {
+        throw new Error(`Unsupported Ralph schemaVersion ${schemaVersion}.`);
+    }
+    const verificationGates = Array.isArray(state.verificationGates)
+        ? [...state.verificationGates]
+        : [];
+    if (!verificationGates.some((gate) => {
+        if (gate === null || typeof gate !== 'object' || Array.isArray(gate))
+            return false;
+        return gate.id === 'contract-parity';
+    })) {
+        verificationGates.push({ id: 'contract-parity', name: 'Contract-parity audit', status: 'pending' });
+    }
+    // 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 linkedUltraworkId = typeof state.linkedUltraworkId === 'string' ? state.linkedUltraworkId : undefined;
+    const taskId = typeof state.taskId === 'string' ? state.taskId : undefined;
+    const validBlockerCategories = [
+        'code-local',
+        'dependency-local',
+        'workflow-state-local',
+        'governance-platform-global',
+    ];
+    const blockerCategory = validBlockerCategories.includes(state.blockerCategory)
+        ? state.blockerCategory
+        : undefined;
+    const architectVerdict = state.architectVerdict && typeof state.architectVerdict === 'object'
+        ? state.architectVerdict
+        : undefined;
+    const architectLoop = typeof state.architectLoop === 'boolean' ? state.architectLoop : undefined;
+    const scopeFidelity = state.scopeFidelity === 'PASS' || state.scopeFidelity === 'FAIL'
+        ? state.scopeFidelity
+        : undefined;
+    const scopeViolations = Array.isArray(state.scopeViolations)
+        ? state.scopeViolations.filter((item) => typeof item === 'string')
+        : undefined;
+    return {
+        ...state,
+        schemaVersion: RALPH_SCHEMA_VERSION,
+        verificationGates,
+        taskIds: Array.isArray(state.taskIds)
+            ? state.taskIds
+            : [],
+        goalScope,
+        gateProfile,
+        linkedUltraworkId,
+        blockerCategory,
+        taskId,
+        architectVerdict,
+        architectLoop,
+        scopeFidelity,
+        scopeViolations,
+    };
+}
+function load(root) {
+    const path = ralphFile(root);
+    const raw = readJsonFile(path);
+    if (raw === undefined) {
+        return null;
+    }
+    return validateJsonFile(path, migrateRalphState(raw), RalphStateSchema);
+}
+function save(root, state) {
+    const next = { ...state, schemaVersion: RALPH_SCHEMA_VERSION, updatedAt: now() };
+    writeJson(ralphFile(root), next);
+    return next;
+}
+export function startRalph(root, opts) {
+    ensureLayout(root);
+    const existing = load(root);
+    if (existing && existing.active) {
+        throw new Error(`Ralph is already active (id=${existing.id}, phase=${existing.phase}). Abort or complete it before starting a new one.`);
+    }
+    // ── Profile selection guard (D4) ─────────────────────────────────────────
+    // explicitProfile: caller supplied gateProfile directly
+    const explicitProfile = opts.gateProfile;
+    const { resolvedProfile, resolvedScope } = explicitProfile === undefined && opts.gates !== undefined
+        ? {
+            resolvedProfile: undefined,
+            resolvedScope: opts.goalScope ?? defaultGoalScopeForRoot(root),
+        }
+        : resolveLifecycleStartScopeAndProfile(root, {
+            text: opts.goal,
+            explicitGoalScope: opts.goalScope,
+            explicitGateProfile: explicitProfile,
+            contextLabel: 'operator_ralph_start',
+            hint: "Supply gateProfile='operator-replacement' for Operator self-hosting work, or 'operator-runtime' for runtime health checks.",
+        });
+    // Determine gate source:
+    //   1. explicit gates param wins (backward compat, custom overrides)
+    //   2. resolved profile (explicit or inferred) → use profile-resolved gates
+    //   3. fallback to DEFAULT_GATES only when no profile resolved (legacy)
+    let gateSource;
+    if (opts.gates !== undefined) {
+        gateSource = opts.gates;
+    }
+    else if (resolvedProfile !== undefined) {
+        const profileGateIds = resolveGateProfile(resolvedProfile);
+        gateSource = profileGateIds.map((id) => ({ id, name: id }));
+    }
+    else {
+        gateSource = DEFAULT_GATES;
+    }
+    const timestamp = lifecycleNow();
+    const gates = gateSource.map((g) => ({ id: g.id, name: g.name, status: 'pending' }));
+    const initialEntry = { phase: 'running', at: timestamp };
+    const state = save(root, {
+        schemaVersion: RALPH_SCHEMA_VERSION,
+        ...buildLifecycleCore({
+            id: `ralph_${randomUUID().slice(0, 12)}`,
+            phase: 'running',
+            history: [initialEntry],
+            goalScope: resolvedScope,
+            gateProfile: resolvedProfile,
+        }),
+        goal: opts.goal,
+        sessionId: opts.sessionId,
+        taskIds: opts.taskIds ?? [],
+        verificationGates: gates,
+        activationMetadata: opts.activationMetadata,
+        linkedUltraworkId: opts.linkedUltraworkId,
+        taskId: opts.taskId,
+    });
+    const shouldBootstrapLocalTracker = state.taskId === undefined && state.taskIds.length === 0;
+    const bootstrappedState = shouldBootstrapLocalTracker
+        ? save(root, {
+            ...state,
+            taskIds: [
+                createLaneTrackerTask(root, {
+                    title: opts.goal,
+                    ownerMode: 'ralph',
+                    ownerStateId: state.id,
+                    initialStatus: 'in_progress',
+                    closureScope: defaultClosureScopeForGoalScope(resolvedScope),
+                    goalScope: resolvedScope,
+                    gateProfile: resolvedProfile,
+                }).id,
+            ],
+        })
+        : state;
+    appendLedger(root, { kind: 'session', action: 'ralph_start', detail: `Ralph started: ${opts.goal}` });
+    appendRalphWorkingMemoryEntry(root, bootstrappedState, '## Confirmed Requirements', `Session started with goal: ${opts.goal}`);
+    upsertInboxItem(root, {
+        kind: 'system',
+        subject: 'Ralph started',
+        body: opts.goal,
+        status: 'open',
+    });
+    clearContinuationState(root, 'ralph started', 'operator_ralph_start');
+    return bootstrappedState;
+}
+export function getRalph(root) {
+    return load(root);
+}
+export function advanceRalph(root, opts) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ralph state found. Start Ralph first.');
+    }
+    assertLifecycleTransitionAllowed('Ralph', state.id, state.phase, opts.toPhase, VALID_TRANSITIONS);
+    const entry = { phase: opts.toPhase, at: lifecycleNow(), by: opts.by, note: opts.note };
+    const next = save(root, {
+        ...state,
+        phase: opts.toPhase,
+        history: [...state.history, entry],
+    });
+    recordLifecyclePhaseTransition(root, {
+        modeType: 'ralph',
+        laneId: state.id,
+        fromPhase: state.phase,
+        toPhase: opts.toPhase,
+        trigger: opts.trigger,
+        sessionAction: `ralph_advance_${opts.toPhase}`,
+        sessionDetail: opts.note ?? `Transitioned to ${opts.toPhase}`,
+        actor: opts.by,
+        sessionId: state.sessionId,
+        runId: state.taskId ?? state.id,
+    });
+    appendRalphWorkingMemoryEntry(root, next, '## Technical Decisions', `Phase advanced to ${opts.toPhase}${opts.note ? ` (${opts.note})` : ''}`);
+    clearContinuationState(root, `ralph advanced to ${opts.toPhase}`, 'operator_ralph_advance');
+    const trackerStatus = trackerStatusForRalphPhase(opts.toPhase);
+    if (trackerStatus) {
+        syncLaneTrackerTasks(root, {
+            ownerMode: 'ralph',
+            ownerStateId: state.id,
+            taskIds: next.taskIds,
+            status: trackerStatus,
+        });
+    }
+    return next;
+}
+export function retargetRalph(root, opts) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('Cannot retarget Ralph: no Ralph state found.');
+    }
+    if (state.phase === 'completed' || state.phase === 'aborted') {
+        throw new Error(`Cannot retarget Ralph "${state.id}": session is in terminal phase="${state.phase}".`);
+    }
+    const { resolvedProfile, resolvedScope } = resolveLifecycleRetargetScopeAndProfile(root, {
+        text: opts.goal,
+        explicitGoalScope: opts.goalScope,
+        explicitGateProfile: opts.gateProfile,
+        currentGoalScope: state.goalScope,
+        currentGateProfile: state.gateProfile,
+        contextLabel: 'operator_ralph_retarget',
+    });
+    if (state.goalScope && resolvedScope && goalScopeRank(resolvedScope) > goalScopeRank(state.goalScope)) {
+        throw new Error(`Cannot retarget Ralph "${state.id}": requested scope "${resolvedScope}" would broaden active scope "${state.goalScope}". Start a new session instead.`);
+    }
+    const event = {
+        oldGoal: state.goal,
+        newGoal: opts.goal,
+        retargetMode: opts.mode,
+        preservedState: opts.mode === 'resume-unchanged'
+            ? 'preserved'
+            : opts.mode === 'narrow-scope'
+                ? 'narrowed'
+                : 'replaced',
+        reason: opts.note ?? `Retargeted goal from "${state.goal}" to "${opts.goal}".`,
+    };
+    const entry = {
+        phase: state.phase,
+        at: lifecycleNow(),
+        by: opts.by,
+        note: opts.note ?? `Retargeted goal from "${state.goal}" to "${opts.goal}"`,
+        retargetEvent: event,
+    };
+    let verificationGates = state.verificationGates;
+    if (resolvedProfile !== undefined) {
+        verificationGates = resolveGateProfile(resolvedProfile).map((id) => ({ id, name: id, status: 'pending' }));
+    }
+    const next = save(root, {
+        ...state,
+        goal: opts.mode === 'resume-unchanged' ? state.goal : opts.goal,
+        goalScope: resolvedScope,
+        gateProfile: resolvedProfile,
+        linkedUltraworkId: opts.linkedUltraworkId ?? state.linkedUltraworkId,
+        verificationGates,
+        history: [...state.history, entry],
+    });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ralph_retarget',
+        detail: `Retargeted Ralph "${state.id}" via ${opts.mode}`,
+        metadata: { id: state.id, mode: opts.mode, goalScope: resolvedScope, gateProfile: resolvedProfile },
+    });
+    if (opts.mode !== 'resume-unchanged') {
+        syncLaneTrackerTasks(root, {
+            ownerMode: 'ralph',
+            ownerStateId: state.id,
+            taskIds: next.taskIds,
+            title: opts.goal,
+            closureScope: defaultClosureScopeForGoalScope(resolvedScope),
+        });
+    }
+    clearContinuationState(root, `ralph retargeted via ${opts.mode}`, 'operator_ralph_retarget');
+    return next;
+}
+export function recordVerification(root, gateId, result) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ralph state found. Start Ralph first.');
+    }
+    const gateIndex = state.verificationGates.findIndex((g) => g.id === gateId);
+    if (gateIndex < 0) {
+        throw new Error(`Unknown gate id: "${gateId}". Known gates: [${state.verificationGates.map((g) => g.id).join(', ')}].`);
+    }
+    const gates = state.verificationGates.map((g, i) => {
+        if (i !== gateIndex)
+            return g;
+        return { ...g, status: result.status, evidence: result.evidence, ranAt: now() };
+    });
+    const next = save(root, {
+        ...state,
+        verificationGates: gates,
+        architectVerdict: result.architectVerdict ?? state.architectVerdict,
+        architectLoop: result.architectLoop ?? state.architectLoop,
+        scopeFidelity: result.scopeFidelity ?? state.scopeFidelity,
+        scopeViolations: result.scopeViolations ?? state.scopeViolations,
+    });
+    appendLedger(root, {
+        kind: 'review',
+        action: `ralph_gate_${result.status}`,
+        detail: `Gate "${gateId}" ${result.status}${result.evidence ? ': ' + result.evidence : ''}`,
+    });
+    const waveVerdict = result.status === 'passed'
+        && (next.architectVerdict?.verdict ?? null) === 'GO'
+        && (next.scopeFidelity ?? 'PASS') === 'PASS'
+        && (next.scopeViolations ?? []).length === 0
+        && next.verificationGates.every((gate) => gate.status === 'passed')
+        ? 'GO'
+        : 'NO-GO';
+    const closureManifest = {
+        lane: 'ralph',
+        sessionId: next.id,
+        gateId,
+        gateStatus: result.status,
+        updatedAt: now(),
+        architectVerdict: next.architectVerdict,
+        scopeFidelity: next.scopeFidelity,
+        scopeViolations: next.scopeViolations,
+        verificationGates: next.verificationGates,
+        waveVerdict,
+        waveResult: result.waveResult,
+    };
+    writeJson(closureManifestFile(root), closureManifest);
+    appendRalphWorkingMemoryEntry(root, next, '## Research Findings', `Verification gate ${gateId} recorded as ${result.status}${result.evidence ? `: ${result.evidence}` : ''}`);
+    clearContinuationState(root, `ralph gate ${gateId} recorded as ${result.status}`, 'operator_ralph_verify');
+    return next;
+}
+export function pauseRalph(root, note) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ralph state found. Start Ralph first.');
+    }
+    const next = save(root, { ...state, active: false });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ralph_pause',
+        detail: note ?? `Ralph paused at phase=${state.phase}`,
+    });
+    return next;
+}
+export function resumeRalph(root, note) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ralph state found. Start Ralph first.');
+    }
+    const resumablePhases = ['running', 'verifying', 'blocked'];
+    if (!resumablePhases.includes(state.phase)) {
+        throw new Error(`Cannot resume Ralph in phase "${state.phase}". Resumable phases: [${resumablePhases.join(', ')}].`);
+    }
+    const next = save(root, { ...state, active: true });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ralph_resume',
+        detail: note ?? `Ralph resumed at phase=${state.phase}`,
+    });
+    return next;
+}
+export function abortRalph(root, reason) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ralph state found. Start Ralph first.');
+    }
+    const allowed = VALID_TRANSITIONS[state.phase];
+    if (!allowed.includes('aborted')) {
+        throw new Error(`Cannot abort Ralph from phase "${state.phase}". Already terminal.`);
+    }
+    const entry = { phase: 'aborted', at: now(), note: reason };
+    const next = save(root, {
+        ...state,
+        phase: 'aborted',
+        active: false,
+        abortReason: reason,
+        history: [...state.history, entry],
+    });
+    appendLedger(root, { kind: 'session', action: 'ralph_abort', detail: reason });
+    upsertInboxItem(root, {
+        kind: 'system',
+        subject: 'Ralph aborted',
+        body: reason,
+        status: 'open',
+    });
+    syncLaneTrackerTasks(root, {
+        ownerMode: 'ralph',
+        ownerStateId: state.id,
+        taskIds: next.taskIds,
+        status: 'cancelled',
+        result: reason,
+    });
+    clearContinuationState(root, reason, 'operator_ralph_abort');
+    return next;
+}
+export function completeRalph(root, summary) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ralph state found. Start Ralph first.');
+    }
+    if (state.phase !== 'verifying') {
+        throw new Error(`completeRalph requires phase="verifying", current phase="${state.phase}".`);
+    }
+    const failedOrPending = state.verificationGates.filter((g) => g.status !== 'passed');
+    if (failedOrPending.length > 0) {
+        throw new Error(`Cannot complete Ralph: gates not passed: [${failedOrPending.map((g) => `${g.id}(${g.status})`).join(', ')}].`);
+    }
+    if (state.architectLoop === true && state.architectVerdict?.verdict === 'NO-GO') {
+        throw new Error(`Cannot complete Ralph: architect verdict is NO-GO. Reasons: [${state.architectVerdict.reasons.join(', ')}].`);
+    }
+    if (!state.architectVerdict || state.architectVerdict.verdict !== 'GO') {
+        throw new Error('Cannot complete Ralph: missing architect approval. Run operator_ralph_verify with architectVerdict.verdict="GO" before completing.');
+    }
+    if (state.scopeFidelity === 'FAIL') {
+        throw new Error(`Cannot complete Ralph: scope-fidelity failed. Prohibited patterns found: [${(state.scopeViolations ?? []).join(', ')}].`);
+    }
+    // Phase 3 completion guard: contract-parity gate must be passed
+    const contractParityGate = state.verificationGates.find((g) => g.id === 'contract-parity');
+    if (contractParityGate && contractParityGate.status !== 'passed') {
+        throw new Error(`Cannot complete Ralph: contract-parity gate is "${contractParityGate.status}". Run operator_contract_parity_run and record the result before completing.`);
+    }
+    const entry = { phase: 'completed', at: now(), note: summary };
+    const next = save(root, {
+        ...state,
+        phase: 'completed',
+        active: false,
+        completionSummary: summary,
+        history: [...state.history, entry],
+    });
+    appendLedger(root, { kind: 'session', action: 'ralph_complete', detail: summary });
+    upsertInboxItem(root, {
+        kind: 'system',
+        subject: 'Ralph completed',
+        body: summary,
+        status: 'open',
+    });
+    syncLaneTrackerTasks(root, {
+        ownerMode: 'ralph',
+        ownerStateId: state.id,
+        taskIds: next.taskIds,
+        status: 'completed',
+        result: summary,
+    });
+    clearContinuationState(root, 'ralph completed', 'operator_ralph_complete');
+    return next;
+}
+export function blockRalph(root, reason, blockerCategory) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ralph state found. Start Ralph first.');
+    }
+    const allowed = VALID_TRANSITIONS[state.phase];
+    if (!allowed.includes('blocked')) {
+        throw new Error(`Cannot block Ralph from phase "${state.phase}". Allowed from ${state.phase}: [${allowed.join(', ') || 'none'}].`);
+    }
+    const entry = { phase: 'blocked', at: now(), note: reason };
+    const next = save(root, {
+        ...state,
+        phase: 'blocked',
+        blockerReason: reason,
+        blockerCategory,
+        evidenceHorizon: createEvidenceHorizon(root),
+        history: [...state.history, entry],
+    });
+    appendLedger(root, { kind: 'session', action: 'ralph_block', detail: reason });
+    syncLaneTrackerTasks(root, {
+        ownerMode: 'ralph',
+        ownerStateId: state.id,
+        taskIds: next.taskIds,
+        status: 'blocked',
+        result: reason,
+    });
+    return next;
+}
+// ── Phase 8 — AzDo task link helpers ────────────────────────────────────────
+export function linkRalphTask(root, taskId) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ralph state found. Start Ralph first.');
+    }
+    if (state.taskId && state.taskId !== taskId) {
+        throw new Error(`Ralph "${state.id}" already linked to "${state.taskId}". ` +
+            `Call unlinkRalphTask first to retarget.`);
+    }
+    const next = save(root, { ...state, taskId });
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ralph_link_task',
+        detail: `Ralph "${state.id}" linked to task "${taskId}"`,
+        metadata: { modeType: 'ralph', modeId: state.id, taskId },
+    });
+    return next;
+}
+export function unlinkRalphTask(root) {
+    ensureLayout(root);
+    const state = load(root);
+    if (!state) {
+        throw new Error('No Ralph state found. Start Ralph first.');
+    }
+    const previous = state.taskId;
+    const { taskId: _removed, ...rest } = state;
+    void _removed;
+    const next = save(root, rest);
+    appendLedger(root, {
+        kind: 'session',
+        action: 'ralph_unlink_task',
+        detail: `Ralph "${state.id}" unlinked from task "${previous ?? 'none'}"`,
+        metadata: { modeType: 'ralph', modeId: state.id, previousTaskId: previous ?? null },
+    });
+    return next;
+}
+//# sourceMappingURL=index.js.map