@deksden-com/dd-flow-cli 0.2.0 → 0.3.0

package/dist/services/protocols.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { parse as parseYaml } from "yaml";
 import { canTransition } from "../domain/contracts.js";
 import { defaultFlowContract, flowContractForState, loadProjectFlowContract } from "../domain/flow-contract.js";
 import { requireStage } from "../domain/validation.js";
@@ -12,6 +13,7 @@ import { appendAudit, getAuditEvents } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
 import { ensureRuntimeProtocolFiles, readPlanFile, readStateFile, writeState } from "../protocol/local-files.js";
 import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProject, codexHomeProfilesForProject, codexHookEventsForProject, hookStatusForProject } from "./hooks.js";
+import { buildProtocolFlowGuidance } from "./flow-guidance.js";
 export function registerProtocol(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
@@ -84,13 +86,17 @@ export function getProtocolStatus(context, input) {
     const runtime = readProtocolRuntimeState(context, protocol);
     const state = runtime.state;
     const plan = readPlanFile(protocol.plan_path);
+    const runDiagnostics = protocolRunDiagnostics(context, protocol, state);
+    const queue = context.db.get("SELECT * FROM merge_queue WHERE protocol_id = ?", [protocol.id]);
     return {
         ok: true,
         protocol: protocolStatusPayload(protocol),
-        diagnostics: runtime.diagnostics,
+        diagnostics: [...runtime.diagnostics, ...runDiagnostics.diagnostics],
+        latest_run: runDiagnostics.latest_run,
         state,
         plan: plan ? summarizePlan(plan) : state.plan,
-        merge_queue: context.db.get("SELECT * FROM merge_queue WHERE protocol_id = ?", [protocol.id]),
+        merge_queue: queue,
+        flow_guidance: buildProtocolFlowGuidance({ state, latestRun: runDiagnostics.latest_run, queueStatus: queue?.status ?? null }),
         worktree: context.db.get("SELECT * FROM worktree_records WHERE protocol_id = ?", [protocol.id]),
         hook_status: hookStatusForProject(context, protocol.project_id),
         codex_home_profiles: codexHomeProfilesForProject(context, protocol.project_id),
@@ -100,6 +106,131 @@ export function getProtocolStatus(context, input) {
         audit: getAuditEvents(context, protocol.id)
     };
 }
+export function getReadyProtocols(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const protocols = protocolDocumentsForProject(project.root).map((document) => protocolSetMemberStatus(context, project.id, document));
+    const boards = protocolSetBoardsForProject(context, project.id, project.root);
+    return {
+        ok: true,
+        project_root: project.root,
+        protocols,
+        ready: protocols.filter((item) => item.set_status === "ready").map((item) => item.id),
+        blocked: protocols.filter((item) => item.set_status === "blocked").map((item) => item.id),
+        running: protocols.filter((item) => item.set_status === "running" || item.set_status === "claimed").map((item) => item.id),
+        done: protocols.filter((item) => item.set_status === "done").map((item) => item.id),
+        protocol_set_boards: boards
+    };
+}
+export function getProtocolBlockers(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const document = requireProtocolDocument(project.root, input.protocolId);
+    const blockers = document.blocked_by_protocols.map((id) => blockerStatus(context, project.id, project.root, id));
+    return {
+        ok: true,
+        project_root: project.root,
+        protocol_id: document.id,
+        protocol_path: document.path,
+        protocol_set: document.protocol_set,
+        blocked_by_protocols: document.blocked_by_protocols,
+        blockers,
+        blocked: blockers.some((blocker) => !blocker.resolved)
+    };
+}
+export function implementProtocol(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const document = requireProtocolDocument(project.root, input.protocolId);
+    const protocol = findProtocol(context, document.id);
+    const runtime = protocol ? readProtocolRuntimeState(context, protocol) : null;
+    const state = runtime?.state ?? null;
+    const terminal = protocolTerminalStatus(context, project.id, project.root, document.id, state);
+    const activeSessions = activeFlowSessionBindingsForProject(context, project.id).filter((session) => session.protocol_id === document.id);
+    const queue = context.db.get("SELECT status, claimed_by_session_id FROM merge_queue WHERE protocol_id = ?", [document.id]);
+    const blockers = document.blocked_by_protocols.map((id) => blockerStatus(context, project.id, project.root, id));
+    const unresolved = blockers.filter((blocker) => !blocker.resolved);
+    const diagnostics = [
+        ...(runtime?.diagnostics ?? []),
+        ...(protocol ? protocolRunDiagnostics(context, protocol, state ?? undefined).diagnostics : []),
+        ...protocolDocumentDiagnostics(document)
+    ];
+    if (terminal.terminal) {
+        throw new AppError("protocol_terminal", "Protocol is terminal and must not be implemented again", 1, {
+            protocol_id: document.id,
+            terminal
+        });
+    }
+    if (unresolved.length > 0 && !input.force) {
+        throw new AppError("protocol_blocked", "Protocol is blocked by unresolved protocols; use --force --reason to override", 1, {
+            protocol_id: document.id,
+            blockers: unresolved
+        });
+    }
+    if (activeSessions.length > 0 && !input.force) {
+        throw new AppError("protocol_claimed", "Protocol already has an active flow session; use --force --reason to override", 1, {
+            protocol_id: document.id,
+            active_sessions: activeSessions
+        });
+    }
+    if (input.force && (!input.reason || input.reason.trim().length === 0)) {
+        throw new AppError("validation", "Forced protocol implement preflight requires --reason", 2);
+    }
+    const currentStage = state?.stage ?? "unregistered";
+    const recommendedPrompt = promptForImplementationStage(currentStage);
+    return {
+        ok: true,
+        mode: "preflight",
+        protocol_id: document.id,
+        project_root: project.root,
+        protocol_path: document.path,
+        protocol_set: document.protocol_set,
+        force: input.force,
+        reason: input.reason ?? null,
+        runtime: protocol
+            ? {
+                registered: true,
+                status: protocol.status,
+                stage: protocol.stage,
+                next_action: protocol.next_action,
+                state_path: protocol.state_path,
+                plan_path: protocol.plan_path
+            }
+            : { registered: false, status: "missing", stage: "unregistered", next_action: "register_protocol" },
+        blockers,
+        active_sessions: activeSessions,
+        merge_queue: queue ?? null,
+        terminal,
+        related_context: document.related_context,
+        coding_standards_sources: document.coding_standards_sources,
+        diagnostics,
+        flow_guidance: {
+            current_stage: currentStage,
+            recommended_next_action: protocol ? recommendedNextActionForImplementationStage(currentStage) : "register_protocol",
+            recommended_prompt: recommendedPrompt,
+            required_predecessor_evidence: currentStage === "unregistered" ? [`dd-flow protocol register ${document.id} --project-root ${JSON.stringify(project.root)} --json`] : [],
+            guards: [
+                {
+                    id: "protocol_blockers_resolved",
+                    status: unresolved.length === 0 || input.force ? "pass" : "fail",
+                    summary: unresolved.length === 0
+                        ? "No unresolved blocked_by_protocols dependencies."
+                        : input.force
+                            ? "Unresolved blockers were force-overridden."
+                            : "Protocol has unresolved blocked_by_protocols dependencies."
+                },
+                {
+                    id: "protocol_not_terminal",
+                    status: terminal.terminal ? "fail" : "pass",
+                    summary: terminal.terminal ? `Protocol is terminal via ${terminal.source}.` : "Protocol is not terminal."
+                },
+                {
+                    id: "protocol_not_claimed",
+                    status: activeSessions.length === 0 || input.force ? "pass" : "fail",
+                    summary: activeSessions.length === 0 ? "No active flow sessions claim this protocol." : "Active flow session already claims this protocol."
+                }
+            ],
+            blocked_if_missing: protocol ? [] : ["runtime protocol registration"]
+        }
+    };
+}
 export function transitionProtocol(context, input) {
     const protocol = requireProtocol(context, input.protocolId);
     const state = readProtocolRuntimeState(context, protocol).state;
@@ -134,13 +265,24 @@ export function transitionProtocol(context, input) {
         ...(input.reason ? { reason: input.reason } : {}),
         payload: { from, to, payload, flow_contract_id: flowContract.id, flow_contract_version: flowContract.version }
     });
-    return { ok: true, protocol_id: protocol.id, from, to, forced: input.force, state: nextState };
+    const runDiagnostics = protocolRunDiagnostics(context, protocol, nextState);
+    const queue = context.db.get("SELECT * FROM merge_queue WHERE protocol_id = ?", [protocol.id]);
+    return {
+        ok: true,
+        protocol_id: protocol.id,
+        from,
+        to,
+        forced: input.force,
+        state: nextState,
+        flow_guidance: buildProtocolFlowGuidance({ state: nextState, latestRun: runDiagnostics.latest_run, queueStatus: queue?.status ?? null })
+    };
 }
 export function readyForMerge(context, input) {
     const protocol = requireProtocol(context, input.protocolId);
     const state = readProtocolRuntimeState(context, protocol).state;
     const flowContract = flowContractForState(state);
     const stage = requireStage(state.stage, flowContract);
+    const runDiagnostics = protocolRunDiagnostics(context, protocol, state);
     const existingQueueJob = context.db.get("SELECT status FROM merge_queue WHERE protocol_id = ?", [
         protocol.id
     ]);
@@ -151,13 +293,22 @@ export function readyForMerge(context, input) {
             eventType: "protocol.ready_for_merge_unchanged",
             payload: { protocol_id: protocol.id, queue_status: existingQueueJob.status, flow_contract_id: flowContract.id }
         });
-        return { ok: true, protocol_id: protocol.id, queue_status: existingQueueJob.status, state };
+        return {
+            ok: true,
+            protocol_id: protocol.id,
+            queue_status: existingQueueJob.status,
+            state,
+            flow_guidance: buildProtocolFlowGuidance({ state, latestRun: runDiagnostics.latest_run, queueStatus: existingQueueJob.status })
+        };
     }
     if (!flowContract.readiness.allowed_from.includes(stage)) {
         throw new AppError("readiness_invalid_stage", "Protocol state does not allow ready-for-merge", 1, {
             stage: state.stage,
             allowed: flowContract.readiness.allowed_from,
-            flow_contract_id: flowContract.id
+            flow_contract_id: flowContract.id,
+            latest_run: runDiagnostics.latest_run,
+            diagnostics: runDiagnostics.diagnostics,
+            recommended_commands: recommendedSyncCommands(protocol, runDiagnostics.latest_run)
         });
     }
     const missing = readinessMissingFields(state);
@@ -193,7 +344,102 @@ export function readyForMerge(context, input) {
         eventType: "protocol.ready_for_merge",
         payload: { protocol_id: protocol.id, queue_status: "ready", flow_contract_id: flowContract.id }
     });
-    return { ok: true, protocol_id: protocol.id, queue_status: "ready", state: nextState };
+    return {
+        ok: true,
+        protocol_id: protocol.id,
+        queue_status: "ready",
+        state: nextState,
+        flow_guidance: buildProtocolFlowGuidance({ state: nextState, latestRun: runDiagnostics.latest_run, queueStatus: "ready" })
+    };
+}
+export function syncProtocolFromRun(context, input) {
+    const protocol = requireProtocol(context, input.protocolId);
+    const state = readProtocolRuntimeState(context, protocol).state;
+    const run = resolveLinkedRun(context, protocol, input.runId);
+    if (run.subject_type !== "protocol" || run.subject_id !== protocol.id) {
+        throw new AppError("protocol_run_subject_mismatch", "Run subject does not match protocol", 1, {
+            protocol_id: protocol.id,
+            run_id: run.id,
+            subject: { type: run.subject_type, id: run.subject_id }
+        });
+    }
+    const index = parseLinkedRunIndex(run.index_json, run.id);
+    const flowContract = flowContractForState(state);
+    const targetStage = input.target === "auto" ? inferSyncTarget(run, index) : requireStage(input.target, flowContract);
+    if (!targetStage) {
+        throw new AppError("sync_target_ambiguous", "Cannot infer protocol sync target from run evidence", 1, {
+            protocol_id: protocol.id,
+            run: linkedRunSummary(run),
+            stage_chain: stageChain(index),
+            allowed_targets: Object.keys(flowContract.stages)
+        });
+    }
+    requireStage(targetStage, flowContract);
+    const now = context.now();
+    const nextState = {
+        ...state,
+        stage: targetStage,
+        status: statusForStage(targetStage, flowContract),
+        next_action: nextActionForSyncedTarget(targetStage),
+        updated_at: now
+    };
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        persistProtocolState(context, protocol, nextState);
+        if (targetStage === "ready_for_merge") {
+            context.db.run(`INSERT INTO merge_queue
+           (protocol_id, project_id, status, claimed_by_session_id, claimed_at, completed_at, created_at, updated_at)
+         VALUES (?, ?, ?, NULL, NULL, NULL, ?, ?)
+         ON CONFLICT(protocol_id) DO UPDATE SET
+           status = CASE WHEN merge_queue.status IN ('merged', 'cancelled', 'failed') THEN merge_queue.status ELSE excluded.status END,
+           updated_at = excluded.updated_at`, [protocol.id, protocol.project_id, "ready", now, now]);
+        }
+        if (targetStage === "closed") {
+            context.db.run(`UPDATE merge_queue
+         SET status = CASE WHEN status IN ('merged', 'cancelled', 'failed') THEN status ELSE 'merged' END,
+             last_reason = COALESCE(last_reason, ?),
+             completed_at = COALESCE(completed_at, ?),
+             updated_at = ?
+         WHERE protocol_id = ?`, [`synced from ${run.id}`, now, now, protocol.id]);
+        }
+        appendAudit(context, {
+            protocolId: protocol.id,
+            projectId: protocol.project_id,
+            eventType: "protocol.synced_from_run",
+            payload: {
+                protocol_id: protocol.id,
+                run_id: run.id,
+                from: state.stage,
+                to: targetStage,
+                target: input.target,
+                run: linkedRunSummary(run),
+                stage_chain: stageChain(index)
+            }
+        });
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    return {
+        ok: true,
+        protocol_id: protocol.id,
+        run_id: run.id,
+        from: state.stage,
+        to: targetStage,
+        state: nextState,
+        flow_guidance: buildProtocolFlowGuidance({
+            state: nextState,
+            latestRun: { ...linkedRunSummary(run), stage_chain: stageChain(index) },
+            queueStatus: targetStage === "ready_for_merge" ? "ready" : null
+        }),
+        evidence_used: {
+            run: linkedRunSummary(run),
+            stage_chain: stageChain(index)
+        },
+        diagnostics: protocolRunDiagnostics(context, protocol, nextState).diagnostics
+    };
 }
 export function cancelProtocol(context, input) {
     const protocol = requireProtocol(context, input.protocolId);
@@ -508,6 +754,33 @@ export function readProtocolRuntimeState(context, protocol) {
     });
     return { state, diagnostics };
 }
+export function protocolRunDiagnostics(context, protocol, state) {
+    const runs = linkedRunsForProtocol(context, protocol, 5);
+    const latest = runs[0];
+    if (!latest) {
+        return { latest_run: null, diagnostics: [] };
+    }
+    const warnings = [];
+    const latestRun = linkedRunSummary(latest);
+    const latestIndex = safeLinkedRunIndex(latest.index_json, latest.id, warnings);
+    const latestWithStages = {
+        ...latestRun,
+        stage_chain: latestIndex ? stageChain(latestIndex) : []
+    };
+    const diagnostics = [...warnings];
+    if (state && isProtocolRunStageMismatch(state.stage, latest, latestIndex)) {
+        diagnostics.push({
+            code: "protocol_run_stage_mismatch",
+            severity: mismatchSeverity(latest, latestIndex),
+            protocol_id: protocol.id,
+            protocol_stage: state.stage,
+            protocol_status: state.status,
+            latest_run: latestWithStages,
+            recommended_commands: recommendedSyncCommands(protocol, latestWithStages)
+        });
+    }
+    return { latest_run: latestWithStages, diagnostics };
+}
 export function persistProtocolState(context, protocol, state) {
     ensureDir(path.dirname(protocol.state_path));
     writeState(protocol.state_path, state);
@@ -537,6 +810,260 @@ export function persistProtocolState(context, protocol, state) {
 function findProtocol(context, protocolId) {
     return context.db.get("SELECT * FROM protocols WHERE id = ?", [protocolId]);
 }
+function protocolDocumentsForProject(projectRoot) {
+    const protocolRoot = path.join(projectRoot, ".memory-bank", "protocol");
+    if (!fs.existsSync(protocolRoot))
+        return [];
+    return fs
+        .readdirSync(protocolRoot, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.startsWith("PRT-") && entry.name.endsWith(".md"))
+        .map((entry) => readProtocolDocument(path.join(protocolRoot, entry.name)))
+        .filter((document) => Boolean(document))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+function requireProtocolDocument(projectRoot, protocolId) {
+    const file = path.join(projectRoot, ".memory-bank", "protocol", `${protocolId}.md`);
+    if (!fs.existsSync(file)) {
+        throw new AppError("protocol_file_not_found", `Protocol markdown is not found: ${protocolId}`, 1, {
+            protocol_id: protocolId,
+            expected_path: file
+        });
+    }
+    const document = readProtocolDocument(file);
+    if (!document) {
+        throw new AppError("protocol_frontmatter_invalid", `Protocol markdown frontmatter is invalid: ${protocolId}`, 1, {
+            protocol_id: protocolId,
+            path: file
+        });
+    }
+    return document;
+}
+function readProtocolDocument(file) {
+    const text = fs.readFileSync(file, "utf8");
+    const match = text.match(/^---\n([\s\S]*?)\n---/);
+    let frontmatter = {};
+    if (match?.[1]) {
+        try {
+            const parsed = parseYaml(match[1]);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                frontmatter = parsed;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    const basename = path.basename(file, ".md");
+    const fileField = stringValue(frontmatter.file);
+    const id = basename;
+    const protocolSet = stringValue(frontmatter.protocol_set);
+    const relatedContext = {};
+    for (const key of [
+        "related_epics",
+        "related_features",
+        "related_specs",
+        "related_adrs",
+        "related_scenarios",
+        "source_user_input",
+        "related_files"
+    ]) {
+        const value = frontmatter[key];
+        if (Array.isArray(value))
+            relatedContext[key] = value.filter((item) => typeof item === "string");
+    }
+    if (fileField)
+        relatedContext.file = fileField;
+    return {
+        id,
+        path: file,
+        frontmatter,
+        protocol_set: protocolSet,
+        blocked_by_protocols: stringArray(frontmatter.blocked_by_protocols),
+        related_context: relatedContext,
+        coding_standards_sources: codingStandardsSources(projectRootFromProtocolFile(file), frontmatter)
+    };
+}
+function protocolDocumentDiagnostics(document) {
+    const diagnostics = [];
+    if (document.protocol_set) {
+        const setPath = path.isAbsolute(document.protocol_set)
+            ? document.protocol_set
+            : path.join(projectRootFromProtocolFile(document.path), document.protocol_set);
+        if (!fs.existsSync(setPath)) {
+            diagnostics.push({
+                code: "protocol_set_file_missing",
+                severity: "warning",
+                protocol_id: document.id,
+                protocol_set: document.protocol_set,
+                expected_path: setPath
+            });
+        }
+    }
+    return diagnostics;
+}
+function protocolSetMemberStatus(context, projectId, document) {
+    const runtime = findProtocol(context, document.id);
+    const state = runtime ? readProtocolRuntimeState(context, runtime).state : null;
+    const queue = context.db.get("SELECT status, claimed_by_session_id FROM merge_queue WHERE protocol_id = ?", [document.id]);
+    const activeSessions = activeFlowSessionBindingsForProject(context, projectId).filter((session) => session.protocol_id === document.id);
+    const projectRoot = projectRootFromProtocolFile(document.path);
+    const blockers = document.blocked_by_protocols.map((id) => blockerStatus(context, projectId, projectRoot, id));
+    const terminal = protocolTerminalStatus(context, projectId, projectRoot, document.id, state);
+    const setStatus = terminal.success
+        ? "done"
+        : queue?.status === "claimed" || activeSessions.length > 0
+            ? "claimed"
+            : state && ["implementation", "readiness", "plan", "specify", "integration", "queued_for_merge", "ready_for_merge"].includes(state.stage)
+                ? "running"
+                : blockers.some((blocker) => !blocker.resolved)
+                    ? "blocked"
+                    : "ready";
+    return {
+        id: document.id,
+        path: document.path,
+        protocol_set: document.protocol_set,
+        set_status: setStatus,
+        blocked_by_protocols: document.blocked_by_protocols,
+        blockers,
+        runtime: runtime
+            ? { registered: true, status: runtime.status, stage: runtime.stage, next_action: runtime.next_action, updated_at: runtime.updated_at }
+            : { registered: false, status: "missing", stage: "unregistered", next_action: "register_protocol" },
+        active_sessions: activeSessions,
+        merge_queue: queue ?? null,
+        terminal
+    };
+}
+export function protocolSetBoardsForProject(context, projectId, projectRoot) {
+    const members = protocolDocumentsForProject(projectRoot)
+        .filter((document) => document.protocol_set)
+        .map((document) => protocolSetMemberStatus(context, projectId, document));
+    const setIds = [...new Set(members.map((member) => member.protocol_set).filter((value) => typeof value === "string"))];
+    return setIds.map((setId) => {
+        const setMembers = members.filter((member) => member.protocol_set === setId);
+        return {
+            protocol_set: setId,
+            summary: {
+                ready: setMembers.filter((member) => member.set_status === "ready").length,
+                blocked: setMembers.filter((member) => member.set_status === "blocked").length,
+                running: setMembers.filter((member) => member.set_status === "running" || member.set_status === "claimed").length,
+                done: setMembers.filter((member) => member.set_status === "done").length,
+                total: setMembers.length
+            },
+            members: setMembers
+        };
+    });
+}
+export function protocolSetBoardForProtocol(context, projectId, projectRoot, protocolId) {
+    const protocolFile = path.join(projectRoot, ".memory-bank", "protocol", `${protocolId}.md`);
+    const document = fs.existsSync(protocolFile) ? readProtocolDocument(protocolFile) : null;
+    if (!document?.protocol_set)
+        return null;
+    return protocolSetBoardsForProject(context, projectId, projectRoot).find((board) => board.protocol_set === document.protocol_set) ?? null;
+}
+function blockerStatus(context, projectId, projectRoot, blockerId) {
+    const runtime = findProtocol(context, blockerId);
+    const state = runtime ? readProtocolRuntimeState(context, runtime).state : null;
+    const terminal = protocolTerminalStatus(context, projectId, projectRoot, blockerId, state);
+    return {
+        id: blockerId,
+        resolved: terminal.success,
+        source: terminal.source,
+        status: runtime?.status ?? terminal.status ?? "unknown",
+        stage: runtime?.stage ?? terminal.stage ?? "unknown",
+        lifecycle: terminal.lifecycle,
+        reason: terminal.reason
+    };
+}
+function protocolTerminalStatus(context, projectId, projectRoot, protocolId, state) {
+    if (state) {
+        if (state.stage === "closed" || state.status === "closed") {
+            return { terminal: true, success: true, source: "runtime_state", status: state.status, stage: state.stage, reason: "runtime protocol is closed" };
+        }
+        if (state.stage === "cancelled" || state.status === "cancelled") {
+            return { terminal: true, success: false, source: "runtime_state", status: state.status, stage: state.stage, reason: "runtime protocol is cancelled" };
+        }
+    }
+    const queue = context.db.get("SELECT status FROM merge_queue WHERE project_id = ? AND protocol_id = ?", [
+        projectId,
+        protocolId
+    ]);
+    if (queue && ["merged"].includes(queue.status)) {
+        return {
+            terminal: true,
+            success: true,
+            source: "merge_queue",
+            status: queue.status,
+            ...(state?.stage ? { stage: state.stage } : {}),
+            reason: "merge queue is merged"
+        };
+    }
+    const protocolFile = path.join(projectRoot, ".memory-bank", "protocol", `${protocolId}.md`);
+    const document = fs.existsSync(protocolFile) ? readProtocolDocument(protocolFile) : null;
+    const lifecycle = document ? stringValue(document.frontmatter.protocol_lifecycle).toUpperCase() : "";
+    if (["MERGED", "CLOSED", "DONE"].includes(lifecycle)) {
+        return { terminal: true, success: true, source: "frontmatter", lifecycle, reason: `protocol_lifecycle is ${lifecycle}` };
+    }
+    if (["CANCELLED"].includes(lifecycle)) {
+        return { terminal: true, success: false, source: "frontmatter", lifecycle, reason: `protocol_lifecycle is ${lifecycle}` };
+    }
+    return {
+        terminal: false,
+        success: false,
+        source: state ? "runtime_state" : document ? "frontmatter" : "missing",
+        ...(state?.status ? { status: state.status } : {}),
+        ...(state?.stage ? { stage: state.stage } : {}),
+        ...(lifecycle ? { lifecycle } : {}),
+        reason: state ? "protocol is not terminal" : document ? "protocol_lifecycle is not terminal success" : "protocol document/runtime not found"
+    };
+}
+function promptForImplementationStage(stage) {
+    if (stage === "unregistered" || stage === "registered" || stage === "priming" || stage === "specify" || stage === "waiting_for_user") {
+        return ".memory-bank/dd-flow/protocol-implement.md";
+    }
+    if (stage === "plan")
+        return ".memory-bank/dd-flow/plan.md";
+    if (["implementation", "readiness"].includes(stage))
+        return ".memory-bank/dd-flow/code.md";
+    if (["ready_for_merge", "queued_for_merge", "integration"].includes(stage))
+        return ".memory-bank/dd-flow/merge.md";
+    return ".memory-bank/dd-flow/protocol-implement.md";
+}
+function recommendedNextActionForImplementationStage(stage) {
+    if (stage === "registered" || stage === "priming" || stage === "specify" || stage === "waiting_for_user")
+        return "continue_specify";
+    if (stage === "plan")
+        return "run_plan_or_code_handoff";
+    if (["implementation", "readiness"].includes(stage))
+        return "run_code_flow";
+    if (["ready_for_merge", "queued_for_merge", "integration"].includes(stage))
+        return "run_merge_flow";
+    if (stage === "unregistered")
+        return "register_protocol";
+    return `continue_${stage}`;
+}
+function codingStandardsSources(projectRoot, frontmatter) {
+    const candidates = [
+        ".memory-bank/spec/engineering/coding-standards.md",
+        ".memory-bank/mbb/coding-standards-guide.md",
+        ".memory-bank/mbb/code-contracts-guide.md",
+        "CONTRIBUTING.md",
+        "README.md"
+    ];
+    const related = [
+        ...stringArray(frontmatter.related_specs),
+        ...stringArray(frontmatter.related_files)
+    ].filter((item) => item.includes("coding") || item.includes("code-contract"));
+    return [...new Set([...related, ...candidates])].filter((candidate) => fs.existsSync(path.isAbsolute(candidate) ? candidate : path.join(projectRoot, candidate)));
+}
+function projectRootFromProtocolFile(file) {
+    return path.dirname(path.dirname(path.dirname(file)));
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : "";
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim().length > 0) : [];
+}
 function inferProtocolId(projectRoot, handshakeId) {
     const directDir = path.join(projectRoot, ".memory-bank", "protocol", handshakeId);
     if (fs.existsSync(directDir)) {
@@ -604,3 +1131,107 @@ function readinessMissingFields(state) {
     }
     return missing;
 }
+function linkedRunsForProtocol(context, protocol, limit) {
+    return context.db.all(`SELECT id, short_id, flow_kind, subject_type, subject_id, status, verdict, next_action, run_index_path, index_json, created_at, updated_at, completed_at
+     FROM flow_runs
+     WHERE project_id = ? AND subject_type = 'protocol' AND subject_id = ?
+     ORDER BY updated_at DESC, id DESC
+     LIMIT ?`, [protocol.project_id, protocol.id, limit]);
+}
+function resolveLinkedRun(context, protocol, runIdOrAlias) {
+    const matches = context.db.all(`SELECT id, short_id, flow_kind, subject_type, subject_id, status, verdict, next_action, run_index_path, index_json, created_at, updated_at, completed_at
+     FROM flow_runs
+     WHERE project_id = ? AND (id = ? OR short_id = ?)
+     ORDER BY updated_at DESC, id DESC`, [protocol.project_id, runIdOrAlias, runIdOrAlias]);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new AppError("ambiguous_alias", `Run alias is ambiguous: ${runIdOrAlias}`, 1, {
+            candidates: matches.map(linkedRunSummary)
+        });
+    }
+    throw new AppError("not_found", `Run is not registered: ${runIdOrAlias}`, 1, { run_id: runIdOrAlias });
+}
+function parseLinkedRunIndex(text, runId) {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new AppError("validation", "Run index is invalid", 2, { run_id: runId });
+    }
+    return value;
+}
+function safeLinkedRunIndex(text, runId, diagnostics) {
+    try {
+        return parseLinkedRunIndex(text, runId);
+    }
+    catch (error) {
+        diagnostics.push({
+            code: "run_index_invalid",
+            severity: "warning",
+            run_id: runId,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return null;
+    }
+}
+function linkedRunSummary(run) {
+    return {
+        id: run.id,
+        short_id: run.short_id,
+        flow_kind: run.flow_kind,
+        status: run.status,
+        verdict: run.verdict,
+        next_action: run.next_action,
+        run_index_path: run.run_index_path,
+        updated_at: run.updated_at,
+        completed_at: run.completed_at
+    };
+}
+function stageChain(index) {
+    return (Array.isArray(index.stage_runs) ? index.stage_runs : [])
+        .map((stage) => `${String(stage.stage ?? "unknown")}:${String(stage.status ?? "unknown")}`);
+}
+function hasDoneStage(index, names) {
+    return Boolean(index?.stage_runs?.some((stage) => typeof stage.stage === "string" && names.includes(stage.stage) && stage.status === "done"));
+}
+function inferSyncTarget(run, index) {
+    if (hasDoneStage(index, ["merge"]) || run.verdict === "merged")
+        return "closed";
+    if (hasDoneStage(index, ["code", "readiness", "implementation"]))
+        return "ready_for_merge";
+    if (hasDoneStage(index, ["plan"]))
+        return "implementation";
+    return null;
+}
+function nextActionForSyncedTarget(targetStage) {
+    if (targetStage === "closed")
+        return "none";
+    if (targetStage === "ready_for_merge")
+        return "run_merge_flow";
+    if (targetStage === "implementation")
+        return "run_code_flow";
+    if (targetStage === "readiness")
+        return "run_readiness_gate";
+    return `continue_${targetStage}`;
+}
+function isProtocolRunStageMismatch(stage, run, index) {
+    if (["closed", "cancelled"].includes(stage))
+        return false;
+    const mergeDone = hasDoneStage(index, ["merge"]) || run.verdict === "merged";
+    if (mergeDone && stage !== "closed")
+        return true;
+    const codeDone = hasDoneStage(index, ["code", "readiness", "implementation"]);
+    if (codeDone && ["registered", "priming", "prime", "specify", "plan", "implementation"].includes(stage))
+        return true;
+    const planDone = hasDoneStage(index, ["plan"]);
+    return planDone && ["registered", "priming", "prime", "specify"].includes(stage);
+}
+function mismatchSeverity(run, index) {
+    return hasDoneStage(index, ["merge"]) || run.verdict === "merged" ? "error" : "warning";
+}
+function recommendedSyncCommands(protocol, latestRun) {
+    if (!latestRun || typeof latestRun.id !== "string")
+        return [];
+    return [
+        `dd-flow protocol sync-from-run ${protocol.id} --run ${latestRun.id} --target auto --project-root ${JSON.stringify(protocol.project_root)} --json`
+    ];
+}