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

package/dist/services/runs.js

@@ -2,12 +2,16 @@ import fs from "node:fs";
 import path from "node:path";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
 import { AppError } from "../shared/errors.js";
-import { ensureDir, runtimeRunJsonPath, userFacingRunDir, userFacingRunIndexPath, resolveProjectRoot } from "../storage/paths.js";
+import { ensureDir, projectRunHome, projectRunIndexPath, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
-const runSchemaId = "dd-flow/flow-run-index@1";
+import { buildRunFlowGuidance } from "./flow-guidance.js";
+import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
+const runSchemaId = "dd-flow/flow-run-index@2";
+const legacyRunSchemaId = "dd-flow/flow-run-index@1";
 const runIdType = "RUN";
 const allowedRunFlowKinds = [
+    "mb_sdlc",
     "coding",
     "experiment",
     "mb-init",
@@ -15,6 +19,8 @@ const allowedRunFlowKinds = [
     "mb-audit",
     "mb-distill",
     "mb-upgrade-review",
+    "mb-sdlc-review",
+    "review",
     "custom"
 ];
 export function startFlowRun(context, input) {
@@ -27,10 +33,10 @@ export function startFlowRun(context, input) {
     const runId = nextRunId(context, slug);
     const { shortId } = parseFullEntityId(runId);
     const now = context.now();
-    const runDirAbsolute = userFacingRunDir(workspaceRoot, runId);
-    const runIndexAbsolute = userFacingRunIndexPath(workspaceRoot, runId);
-    const runDirRelative = path.relative(workspaceRoot, runDirAbsolute);
-    const runtimePath = runtimeRunJsonPath(context.ddFlowHome, project.id, runId);
+    const runHome = projectRunHome(context.ddFlowHome, project.id, runId);
+    const runIndexAbsolute = projectRunIndexPath(context.ddFlowHome, project.id, runId);
+    const runDirRelative = path.posix.join("runs", runId);
+    const runtimePath = projectRunJsonPath(context.ddFlowHome, project.id, runId);
     const index = {
         schema_id: runSchemaId,
         run_id: runId,
@@ -48,6 +54,18 @@ export function startFlowRun(context, input) {
             root: workspaceRoot,
             run_dir: runDirRelative
         },
+        run_home: {
+            storage: "dd_flow_home",
+            path: runHome,
+            relative_path: runDirRelative
+        },
+        execution: {
+            project_root: project.root,
+            workspace_root: workspaceRoot
+        },
+        legacy: {
+            project_tasks_run_dir: null
+        },
         stage_runs: [],
         sessions: [],
         artifacts: [],
@@ -58,13 +76,14 @@ export function startFlowRun(context, input) {
         updated_at: now
     };
     ensureDir(path.dirname(runtimePath));
-    ensureDir(runDirAbsolute);
+    ensureDir(runHome);
     writeJsonFile(runtimePath, index);
     writeJsonFile(runIndexAbsolute, index);
     context.db.run(`INSERT INTO flow_runs
       (id, short_id, slug, project_id, project_root, workspace_root, flow_kind, subject_type, subject_id,
-       status, verdict, next_action, runtime_path, run_dir, run_index_path, index_json, created_at, updated_at, completed_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)`, [
+       status, verdict, next_action, runtime_path, run_dir, run_index_path, run_home_path, layout_version, artifact_root_kind,
+       index_json, created_at, updated_at, completed_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)`, [
         runId,
         shortId,
         slug,
@@ -78,8 +97,11 @@ export function startFlowRun(context, input) {
         index.verdict,
         index.next_action,
         runtimePath,
-        runDirRelative,
+        runHome,
         runIndexAbsolute,
+        runHome,
+        "home_run_v2",
+        "dd_flow_home",
         JSON.stringify(index),
         now,
         now
@@ -87,14 +109,15 @@ export function startFlowRun(context, input) {
     appendAudit(context, {
         projectId: project.id,
         eventType: "flow_run.started",
-        payload: { run_id: runId, flow_kind: flowKind, subject: index.subject, workspace_root: workspaceRoot }
+        payload: { run_id: runId, flow_kind: flowKind, subject: index.subject, workspace_root: workspaceRoot, run_home: runHome }
     });
     return { ok: true, run: flowRunSummary(requireRunById(context, project.id, runId)), index };
 }
 export function getFlowRunStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    return { ok: true, run: flowRunSummary(run), index: parseRunIndex(run.index_json) };
+    const index = parseRunIndex(run.index_json);
+    return { ok: true, run: flowRunSummary(run), index, flow_guidance: guidanceForRun(context, run, index) };
 }
 export function listFlowRuns(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -114,6 +137,9 @@ export function attachFlowRunStage(context, input) {
     const dir = requiredStageDir(input.dir);
     const status = parseStageStatus(input.status);
     const existing = index.stage_runs.find((item) => item.stage === stage);
+    if (status === "running" && existing) {
+        archiveExistingStageAttempt(runArtifactRoot(run), dir);
+    }
     const stageRun = {
         ...(existing ?? { order: index.stage_runs.length + 1 }),
         stage,
@@ -130,7 +156,8 @@ export function attachFlowRunStage(context, input) {
         eventType: "flow_run.stage_attached",
         payload: { run_id: run.id, stage, dir, status }
     });
-    return { ok: true, run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
+    const updatedRun = requireRunById(context, project.id, run.id);
+    return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
 export function completeFlowRunStage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -161,7 +188,8 @@ export function completeFlowRunStage(context, input) {
         eventType: "flow_run.stage_completed",
         payload: { run_id: run.id, stage, status, stage_report: input.stageReport ?? null, data: input.data ?? null }
     });
-    return { ok: true, run: flowRunSummary(requireRunById(context, project.id, run.id)), stage_run: stageRun, index };
+    const updatedRun = requireRunById(context, project.id, run.id);
+    return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
 export function completeFlowRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -182,11 +210,32 @@ export function completeFlowRun(context, input) {
         eventType: "flow_run.completed",
         payload: { run_id: run.id, status, verdict: index.verdict, next_action: index.next_action }
     });
-    return { ok: true, run: flowRunSummary(requireRunById(context, project.id, run.id)), index };
+    const updatedRun = requireRunById(context, project.id, run.id);
+    return { ok: true, run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
+}
+function guidanceForRun(context, run, index) {
+    if (run.subject_type === "protocol") {
+        try {
+            const protocol = requireProtocol(context, run.subject_id);
+            const state = readProtocolRuntimeState(context, protocol).state;
+            return buildRunFlowGuidance({
+                stageRuns: index.stage_runs,
+                protocolStage: state.stage,
+                ...(state.flow_contract ? { contract: state.flow_contract } : {}),
+                runId: run.id,
+                runDir: index.run_home?.relative_path ?? index.workspace.run_dir
+            });
+        }
+        catch (error) {
+            if (!(error instanceof AppError && error.code === "not_found"))
+                throw error;
+        }
+    }
+    return buildRunFlowGuidance({ stageRuns: index.stage_runs, runId: run.id, runDir: index.run_home?.relative_path ?? index.workspace.run_dir });
 }
 function persistRunIndex(context, project, run, index) {
-    const runtimePath = runtimeRunJsonPath(context.ddFlowHome, project.id, run.id);
-    const runIndexPath = userFacingRunIndexPath(run.workspace_root, run.id);
+    const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, project.id, run.id);
+    const runIndexPath = run.run_index_path || projectRunIndexPath(context.ddFlowHome, project.id, run.id);
     ensureDir(path.dirname(runtimePath));
     ensureDir(path.dirname(runIndexPath));
     writeJsonFile(runtimePath, index);
@@ -281,6 +330,9 @@ function flowRunSummary(run) {
         runtime_path: run.runtime_path,
         run_dir: run.run_dir,
         run_index_path: run.run_index_path,
+        run_home_path: run.run_home_path ?? null,
+        layout_version: run.layout_version ?? null,
+        artifact_root_kind: run.artifact_root_kind ?? null,
         created_at: run.created_at,
         updated_at: run.updated_at,
         completed_at: run.completed_at
@@ -288,19 +340,20 @@ function flowRunSummary(run) {
 }
 function parseRunIndex(text) {
     const index = JSON.parse(text);
-    if (index.schema_id !== runSchemaId) {
+    if (index.schema_id !== runSchemaId && index.schema_id !== legacyRunSchemaId) {
         throw new AppError("validation", `Invalid run index schema: ${String(index.schema_id)}`, 2);
     }
     return index;
 }
 function parseRunFlowKind(value) {
-    if (!allowedRunFlowKinds.includes(value)) {
+    const normalized = value === "mb-sdlc" ? "mb_sdlc" : value;
+    if (!allowedRunFlowKinds.includes(normalized)) {
         throw new AppError("validation", "flow-kind is not supported for run start", 2, {
             flow_kind: value,
             allowed: allowedRunFlowKinds
         });
     }
-    return value;
+    return normalized;
 }
 function parseRunStatus(value) {
     if (!["running", "done", "blocked", "cancelled", "failed"].includes(value)) {
@@ -354,6 +407,30 @@ function resolveWorkspaceRoot(workspaceRoot) {
     }
     return fs.realpathSync(absolute);
 }
+function archiveExistingStageAttempt(runRoot, stageDir) {
+    const currentStageDir = path.join(runRoot, stageDir);
+    if (!fs.existsSync(currentStageDir) || !fs.statSync(currentStageDir).isDirectory()) {
+        return;
+    }
+    const entries = fs.readdirSync(currentStageDir).filter((entry) => !/^try-\d{3}$/.test(entry));
+    if (entries.length === 0) {
+        return;
+    }
+    let attempt = 1;
+    while (fs.existsSync(path.join(currentStageDir, `try-${String(attempt).padStart(3, "0")}`))) {
+        attempt += 1;
+    }
+    const archiveDir = path.join(currentStageDir, `try-${String(attempt).padStart(3, "0")}`);
+    ensureDir(archiveDir);
+    for (const entry of entries) {
+        fs.renameSync(path.join(currentStageDir, entry), path.join(archiveDir, entry));
+    }
+}
 function writeJsonFile(file, value) {
-    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+    const tmpFile = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmpFile, `${JSON.stringify(value, null, 2)}\n`);
+    fs.renameSync(tmpFile, file);
+}
+function runArtifactRoot(run) {
+    return path.dirname(run.run_index_path);
 }

package/dist/services/schema-validation.js

@@ -16,6 +16,20 @@ const mandatoryMbUpgradeReviewAspectIds = [
     "09-report-quality",
     "10-agent-process-quality"
 ];
+const mandatoryMbSdlcReviewAspectIds = [
+    "structure_navigation_review",
+    "feature_epic_layer_review",
+    "spec_conformance_review",
+    "architecture_harmonization_review",
+    "adr_decision_review",
+    "scenario_evidence_review",
+    "contract_traceability_review",
+    "frontmatter_crosslink_review",
+    "engineering_standards_review",
+    "operations_policy_review",
+    "protocol_delivery_trace_review",
+    "def_followup_review"
+];
 export function validateSchema(options) {
     if (!schemaNamePattern.test(options.schemaName)) {
         throw new AppError("usage", "--schema must be a schema name such as mb-upgrade-review-data", 2);
@@ -97,14 +111,17 @@ function formatAjvError(error) {
     };
 }
 function validateSemanticSchema(schemaName, data) {
-    if (schemaName !== "mb-upgrade-review-data") {
-        return [];
-    }
     const root = asRecord(data);
     if (!root) {
         return [];
     }
-    return validateMbUpgradeReviewData(root);
+    if (schemaName === "mb-upgrade-review-data") {
+        return validateMbUpgradeReviewData(root);
+    }
+    if (schemaName === "mb-sdlc-review-report") {
+        return validateMbSdlcReviewReport(root);
+    }
+    return [];
 }
 function validateMbUpgradeReviewData(root) {
     const errors = [];
@@ -159,6 +176,69 @@ function validateMbUpgradeReviewData(root) {
     });
     return errors;
 }
+function validateMbSdlcReviewReport(root) {
+    const errors = [];
+    const aspects = arrayValue(root, "aspect_coverage").filter(isRecord);
+    const findings = arrayValue(root, "findings_register").filter(isRecord);
+    const conformance = recordValue(root, "conformance_summary");
+    const verdict = conformance ? stringValue(conformance, "overall_verdict") : undefined;
+    const aspectIds = aspects.map((aspect) => stringValue(aspect, "aspect_id")).filter(isString);
+    for (const id of mandatoryMbSdlcReviewAspectIds) {
+        const count = aspectIds.filter((value) => value === id).length;
+        if (count !== 1) {
+            errors.push({
+                path: "/aspect_coverage",
+                message: `mandatory aspect ${id} must be present exactly once`,
+                keyword: "dd-flow/aspect-id"
+            });
+        }
+    }
+    const findingIds = new Set(findings.map((finding) => stringValue(finding, "id")).filter(isString));
+    aspects.forEach((aspect, aspectIndex) => {
+        const refs = arrayValue(aspect, "findings").filter(isString);
+        refs.forEach((ref, refIndex) => {
+            if (!findingIds.has(ref)) {
+                errors.push({
+                    path: `/aspect_coverage/${aspectIndex}/findings/${refIndex}`,
+                    message: `finding reference does not exist: ${ref}`,
+                    keyword: "dd-flow/finding-ref"
+                });
+            }
+        });
+    });
+    const decisions = recordValue(root, "critic_pass")
+        ? arrayValue(recordValue(root, "critic_pass"), "decisions").filter(isRecord)
+        : [];
+    decisions.forEach((decision, decisionIndex) => {
+        const findingId = stringValue(decision, "finding_id");
+        const disposition = stringValue(decision, "disposition");
+        if (findingId && !findingIds.has(findingId)) {
+            errors.push({
+                path: `/critic_pass/decisions/${decisionIndex}/finding_id`,
+                message: `critic decision finding_id does not exist: ${findingId}`,
+                keyword: "dd-flow/finding-ref"
+            });
+        }
+        if (disposition === "accepted" && !findingId) {
+            errors.push({
+                path: `/critic_pass/decisions/${decisionIndex}/finding_id`,
+                message: "accepted critic decision must reference a final finding_id",
+                keyword: "dd-flow/accepted-finding-ref"
+            });
+        }
+    });
+    findings.forEach((finding, findingIndex) => {
+        const severity = stringValue(finding, "severity");
+        if ((verdict === "accepted" || verdict === "accepted_with_findings") && severity === "blocking") {
+            errors.push({
+                path: `/findings_register/${findingIndex}/severity`,
+                message: "accepted review verdict cannot coexist with blocking findings",
+                keyword: "dd-flow/accepted-blocking"
+            });
+        }
+    });
+    return errors;
+}
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
 }

package/dist/services/sessions.js

@@ -5,6 +5,7 @@ import { AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
+import { cancelLaneWaitersForWorker } from "./lanes.js";
 export function registerFlowSession(context, input) {
     const payload = decodeFlowSessionPayload(input);
     const project = requireProjectByRoot(context, resolveProjectRoot(payload.project_root));
@@ -44,16 +45,21 @@ export function stopMergeWorker(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const sessions = flowSessionsForProject(context, project.id, { workerId: input.workerId }).filter((session) => session.flow_kind === "merge_worker" && ["active", "pending", "stopping"].includes(session.status));
     let lock_release = { ok: true, released: false, reason: "no_active_session" };
+    let waiter_cancellation = { ok: true, cancelled: 0 };
     for (const session of sessions) {
-        lock_release = markSessionStopped(context, project, session, input.reason) ?? lock_release;
+        const stopped = markSessionStopped(context, project, session, input.reason);
+        if (isStopResult(stopped)) {
+            lock_release = stopped.lock_release ?? lock_release;
+            waiter_cancellation = stopped.waiter_cancellation ?? waiter_cancellation;
+        }
     }
     appendAudit(context, {
         projectId: project.id,
         eventType: "flow_session.merge_worker_stopped",
         reason: input.reason,
-        payload: { project_id: project.id, worker_id: input.workerId, stopped_sessions: sessions.length, lock_release }
+        payload: { project_id: project.id, worker_id: input.workerId, stopped_sessions: sessions.length, lock_release, waiter_cancellation }
     });
-    return { ok: true, stopped_sessions: sessions.length, lock_release };
+    return { ok: true, stopped_sessions: sessions.length, lock_release, waiter_cancellation };
 }
 export function stoppedMergeWorkerState(context, projectId, workerId) {
     const latest = context.db.get(`SELECT status, stop_reason FROM flow_sessions
@@ -268,6 +274,14 @@ function markSessionStopped(context, project, session, reason) {
      SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
      WHERE project_id = ? AND session_id = ?`, [reason, now, now, project.id, session.session_id]);
     let lockRelease = undefined;
+    let waiterCancellation = undefined;
+    if (session.worker_id) {
+        waiterCancellation = cancelLaneWaitersForWorker(context, {
+            projectRoot: project.root,
+            workerId: session.worker_id,
+            reason
+        });
+    }
     if ((session.flow_kind === "merge_worker" || session.flow_kind === "merge_job") && session.worker_id) {
         lockRelease = releaseMergeLockIfOwned(context, project.root, session.worker_id, reason);
     }
@@ -278,7 +292,10 @@ function markSessionStopped(context, project, session, reason) {
         payload: { project_id: project.id, session_id: session.session_id, flow_kind: session.flow_kind },
         ...(session.protocol_id ? { protocolId: session.protocol_id } : {})
     });
-    return lockRelease;
+    return { lock_release: lockRelease, waiter_cancellation: waiterCancellation };
+}
+function isStopResult(value) {
+    return Boolean(value && typeof value === "object" && ("lock_release" in value || "waiter_cancellation" in value));
 }
 function releaseMergeLockIfOwned(context, projectRoot, workerId, reason) {
     const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));

package/dist/services/status.js

@@ -1,7 +1,13 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { getCanonStatus } from "./canon.js";
 import { getCliBuildInfo } from "./build-info.js";
 import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-status.js";
 import { findProjectByRoot } from "./projects.js";
+import { classifyCliOperation } from "./cli-operation-classifier.js";
+import { compatibilityReport } from "./compatibility-preflight.js";
+import { selectEngine } from "./engines.js";
 export function getRuntimeStatus(context, input = {}) {
     const cwd = process.cwd();
     const projectRootResolution = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd });
@@ -16,12 +22,20 @@ export function getRuntimeStatus(context, input = {}) {
         canon: resolvedCanonForProject
     });
     const cli = getCliBuildInfo();
+    const compatibilityManifest = resolvedCanonForProject ? readCompatibilityManifest(canon) : null;
+    const cliCompatibility = cliCompatibilityVerdict(cli, compatibilityManifest);
+    const engineSelection = projectRoot ? selectEngine(context, { projectRoot }) : null;
+    const registry = input.checkRegistry ? checkNpmRegistry(context, cli.package_name) : undefined;
     return {
         ok: true,
         schema_id: "dd-flow/status-report@1",
         dd_flow_home: context.ddFlowHome,
         cwd,
-        cli,
+        cli: {
+            ...cli,
+            compatibility: cliCompatibility,
+            ...(registry ? { registry } : {})
+        },
         project: {
             requested_root: projectRootResolution.requested_root,
             root: projectRoot,
@@ -33,6 +47,12 @@ export function getRuntimeStatus(context, input = {}) {
             flow_pack: projectVersionStatus?.flow_pack ?? null,
             drift: projectVersionStatus?.drift ?? null
         },
+        engine: engineSelection
+            ? {
+                selection: engineSelection,
+                compatibility: compatibilityReport(engineSelection, classifyCliOperation(["status"]))
+            }
+            : null,
         canon: {
             ...(asRecord(canonStatus) ?? {}),
             resolved: canon ?? null,
@@ -46,6 +66,184 @@ function asRecord(value) {
 function stringValue(value) {
     return typeof value === "string" && value.length > 0 ? value : null;
 }
+function readCompatibilityManifest(canon) {
+    const record = asRecord(canon);
+    const memorybankRoot = stringValue(record?.memorybank_root);
+    if (!memorybankRoot)
+        return null;
+    const file = path.join(memorybankRoot, "dd-flow", "compatibility.json");
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        const root = asRecord(parsed);
+        const cli = asRecord(root?.dd_flow_cli);
+        if (!root || !cli)
+            return null;
+        return {
+            schema_id: stringValue(root.schema_id),
+            memory_bank_version: stringValue(root.memory_bank_version),
+            dd_flow_cli: {
+                package_name: stringValue(cli.package_name),
+                min_version: stringValue(cli.min_version),
+                recommended_version: stringValue(cli.recommended_version),
+                status_contract: stringValue(cli.status_contract),
+                version_contract: stringValue(cli.version_contract),
+                flow_contract: stringValue(cli.flow_contract)
+            }
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function cliCompatibilityVerdict(cli, manifest) {
+    if (!manifest) {
+        return {
+            verdict: "unknown",
+            reason: "compatibility_manifest_missing",
+            package_name: cli.package_name,
+            installed_version: cli.version,
+            update_command: null
+        };
+    }
+    const expectedPackage = manifest.dd_flow_cli.package_name;
+    if (expectedPackage && expectedPackage !== cli.package_name) {
+        return {
+            verdict: "incompatible",
+            reason: "package_name_mismatch",
+            package_name: cli.package_name,
+            expected_package_name: expectedPackage,
+            installed_version: cli.version,
+            memory_bank_version: manifest.memory_bank_version,
+            min_version: manifest.dd_flow_cli.min_version,
+            recommended_version: manifest.dd_flow_cli.recommended_version,
+            update_command: updateCommand(expectedPackage, manifest.dd_flow_cli.recommended_version ?? manifest.dd_flow_cli.min_version)
+        };
+    }
+    const minVersion = manifest.dd_flow_cli.min_version;
+    const recommendedVersion = manifest.dd_flow_cli.recommended_version;
+    const installed = parseSemver(cli.version);
+    const min = minVersion ? parseSemver(minVersion) : null;
+    const recommended = recommendedVersion ? parseSemver(recommendedVersion) : null;
+    if (!installed || (minVersion && !min) || (recommendedVersion && !recommended)) {
+        return {
+            verdict: "unknown",
+            reason: "invalid_semver",
+            package_name: cli.package_name,
+            installed_version: cli.version,
+            memory_bank_version: manifest.memory_bank_version,
+            min_version: minVersion,
+            recommended_version: recommendedVersion,
+            update_command: null
+        };
+    }
+    if (min && compareSemver(installed, min) < 0) {
+        return {
+            verdict: "incompatible",
+            reason: "installed_below_min_version",
+            package_name: cli.package_name,
+            installed_version: cli.version,
+            memory_bank_version: manifest.memory_bank_version,
+            min_version: minVersion,
+            recommended_version: recommendedVersion,
+            update_command: updateCommand(cli.package_name, recommendedVersion ?? minVersion)
+        };
+    }
+    if (recommended && compareSemver(installed, recommended) < 0) {
+        return {
+            verdict: "outdated",
+            reason: "installed_below_recommended_version",
+            package_name: cli.package_name,
+            installed_version: cli.version,
+            memory_bank_version: manifest.memory_bank_version,
+            min_version: minVersion,
+            recommended_version: recommendedVersion,
+            update_command: updateCommand(cli.package_name, recommendedVersion)
+        };
+    }
+    return {
+        verdict: "ok",
+        reason: "installed_satisfies_memory_bank_compatibility",
+        package_name: cli.package_name,
+        installed_version: cli.version,
+        memory_bank_version: manifest.memory_bank_version,
+        min_version: minVersion,
+        recommended_version: recommendedVersion,
+        status_contract: manifest.dd_flow_cli.status_contract,
+        version_contract: manifest.dd_flow_cli.version_contract,
+        flow_contract: manifest.dd_flow_cli.flow_contract,
+        update_command: null
+    };
+}
+function updateCommand(packageName, version) {
+    return `pnpm add -g ${packageName}${version ? `@${version}` : "@latest"}`;
+}
+function checkNpmRegistry(context, packageName) {
+    const cachePath = path.join(context.ddFlowHome, "cache", "npm", `${safeCacheName(packageName)}.json`);
+    const cached = readRegistryCache(cachePath);
+    const now = new Date().toISOString();
+    if (cached && Date.now() - cached.checkedAtMs < 15 * 60 * 1000) {
+        return { ...cached.payload, source: "npm_cache" };
+    }
+    const result = spawnSync("npm", ["view", packageName, "version", "--json"], { encoding: "utf8", timeout: 5000 });
+    if (result.status !== 0) {
+        return {
+            package_name: packageName,
+            latest: null,
+            checked_at: now,
+            source: "npm",
+            status: "degraded",
+            reason: result.error ? String(result.error) : result.stderr.trim() || "npm_view_failed"
+        };
+    }
+    const latest = parseRegistryVersion(result.stdout);
+    const payload = {
+        package_name: packageName,
+        latest,
+        checked_at: now,
+        source: "npm",
+        status: latest ? "ok" : "degraded",
+        ...(latest ? {} : { reason: "npm_view_returned_no_version" })
+    };
+    writeRegistryCache(cachePath, payload);
+    return payload;
+}
+function readRegistryCache(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        const record = asRecord(parsed);
+        const payload = asRecord(record?.payload);
+        const checkedAt = stringValue(record?.checked_at);
+        if (!payload || !checkedAt)
+            return null;
+        const checkedAtMs = Date.parse(checkedAt);
+        return Number.isNaN(checkedAtMs) ? null : { checkedAtMs, payload };
+    }
+    catch {
+        return null;
+    }
+}
+function writeRegistryCache(file, payload) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify({ checked_at: payload.checked_at, payload }, null, 2)}\n`);
+    }
+    catch {
+        // Registry cache is best effort; status remains valid without it.
+    }
+}
+function parseRegistryVersion(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed === "string" && parsed.length > 0 ? parsed : null;
+    }
+    catch {
+        const trimmed = value.trim().replace(/^"|"$/g, "");
+        return trimmed.length > 0 ? trimmed : null;
+    }
+}
+function safeCacheName(value) {
+    return value.replace(/[^a-zA-Z0-9_.-]+/g, "_");
+}
 function canonForProjectStatus(value) {
     const record = asRecord(value);
     if (!record || typeof record.root !== "string")