@deksden-com/dd-flow-cli 0.6.0 → 0.7.0

package/dist/services/run-engine-bindings.js

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+export const runEngineBindingSchemaId = "dd-flow/run-engine-binding@1";
+export function findRunHome(ddFlowHome, projectRoot, runIdOrAlias) {
+    const projectsRoot = path.join(ddFlowHome, "projects");
+    if (!fs.existsSync(projectsRoot))
+        return null;
+    const expectedRoot = realpathOrResolve(projectRoot);
+    const matches = [];
+    for (const projectId of fs.readdirSync(projectsRoot)) {
+        const runsRoot = path.join(projectsRoot, projectId, "runs");
+        if (!isDirectory(runsRoot))
+            continue;
+        for (const runId of fs.readdirSync(runsRoot)) {
+            if (!runIdMatches(runId, runIdOrAlias))
+                continue;
+            const runHome = path.join(runsRoot, runId);
+            const authorityPath = path.join(runHome, "run.json");
+            const bindingPath = path.join(runHome, "engine-binding.json");
+            const binding = readRunEngineBinding(bindingPath, { allowMissing: true });
+            const authorityRoot = binding?.project_root ?? projectRootFromAuthority(authorityPath);
+            if (!authorityRoot || realpathOrResolve(authorityRoot) !== expectedRoot)
+                continue;
+            matches.push({ project_id: projectId, run_id: runId, run_home: runHome, authority_path: authorityPath, binding_path: bindingPath });
+        }
+    }
+    if (matches.length > 1) {
+        throw new AppError("ambiguous_id", `RUN id is ambiguous for project: ${runIdOrAlias}`, 2, {
+            project_root: expectedRoot,
+            candidates: matches.map((match) => match.run_id)
+        });
+    }
+    return matches[0] ?? null;
+}
+export function readRunEngineBinding(file, options = {}) {
+    if (!fs.existsSync(file)) {
+        if (options.allowMissing)
+            return null;
+        throw new AppError("run_engine_binding_missing", "RUN engine binding is missing", 1, { path: file });
+    }
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new AppError("run_engine_binding_invalid", "RUN engine binding is not valid JSON", 2, { path: file, cause: String(error) });
+    }
+    if (!isRunEngineBinding(value)) {
+        throw new AppError("run_engine_binding_invalid", "RUN engine binding is invalid", 2, { path: file });
+    }
+    return value;
+}
+export function writeRunEngineBinding(file, binding) {
+    const existing = readRunEngineBinding(file, { allowMissing: true });
+    if (existing) {
+        if (sameEngine(existing.engine, binding.engine) && existing.run_id === binding.run_id && realpathOrResolve(existing.project_root) === realpathOrResolve(binding.project_root)) {
+            return { changed: false, binding: existing };
+        }
+        throw new AppError("run_engine_binding_immutable", "RUN engine binding cannot be changed", 1, {
+            path: file,
+            current: existing.engine,
+            requested: binding.engine
+        });
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(binding, null, 2)}\n`);
+    fs.renameSync(temporary, file);
+    return { changed: true, binding };
+}
+export function allRunEngineBindings(ddFlowHome) {
+    const projectsRoot = path.join(ddFlowHome, "projects");
+    if (!fs.existsSync(projectsRoot))
+        return [];
+    const bindings = [];
+    for (const projectId of fs.readdirSync(projectsRoot)) {
+        const runsRoot = path.join(projectsRoot, projectId, "runs");
+        if (!isDirectory(runsRoot))
+            continue;
+        for (const runId of fs.readdirSync(runsRoot)) {
+            const binding = readRunEngineBinding(path.join(runsRoot, runId, "engine-binding.json"), { allowMissing: true });
+            if (binding)
+                bindings.push(binding);
+        }
+    }
+    return bindings;
+}
+function isRunEngineBinding(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    const engine = record.engine;
+    const probe = record.probe;
+    return record.schema_id === runEngineBindingSchemaId
+        && typeof record.run_id === "string"
+        && typeof record.project_root === "string"
+        && typeof record.bound_at === "string"
+        && ["run_creation", "legacy_recovery"].includes(String(record.source))
+        && typeof record.reason === "string"
+        && Boolean(engine && typeof engine === "object" && !Array.isArray(engine)
+            && typeof engine.package_name === "string"
+            && typeof engine.package_version === "string"
+            && typeof engine.engine_version === "string"
+            && /^[a-f0-9]{64}$/.test(String(engine.integrity_checksum))
+            && typeof engine.snapshot_root === "string")
+        && Boolean(probe && typeof probe === "object" && !Array.isArray(probe)
+            && ["not_required", "passed"].includes(String(probe.status))
+            && (typeof probe.command === "string" || probe.command === null));
+}
+function sameEngine(left, right) {
+    return left.package_name === right.package_name
+        && left.package_version === right.package_version
+        && left.engine_version === right.engine_version
+        && left.integrity_checksum === right.integrity_checksum
+        && left.snapshot_root === right.snapshot_root;
+}
+function projectRootFromAuthority(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        const execution = recordValue(value.execution);
+        const workspace = recordValue(value.workspace);
+        const project = recordValue(value.project);
+        return stringValue(execution?.project_root)
+            ?? stringValue(workspace?.project_root)
+            ?? stringValue(project?.root)
+            ?? stringValue(value.project_root);
+    }
+    catch {
+        return null;
+    }
+}
+function runIdMatches(fullId, idOrAlias) {
+    return fullId === idOrAlias || /^RUN-[0-9]+$/.test(idOrAlias) && fullId.startsWith(`${idOrAlias}-`);
+}
+function isDirectory(value) {
+    try {
+        return fs.statSync(value).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function realpathOrResolve(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/services/runs.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
-import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
+import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadCanonicalFlowContract, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
 import { ensureDir, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
@@ -12,6 +12,8 @@ import { buildRunFlowGuidance } from "./flow-guidance.js";
 import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { checkpointRunUsage, usageForRun } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
+import { resolveCanonRoot } from "./canon.js";
+import { bindCurrentEngineToRun } from "./engines.js";
 const runSchemaId = "dd-flow/flow-run@2";
 const runtimeSchemaId = "dd-flow/flow-run@2";
 const runIdType = "RUN";
@@ -30,7 +32,9 @@ const allowedRunFlowKinds = [
 ];
 export function startFlowRun(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const flowContract = loadProjectFlowContract(projectRoot);
+    const flowContract = input.flowKind === "mb-upgrade"
+        ? loadUpgradeFlowContract(context, projectRoot)
+        : loadProjectFlowContract(projectRoot);
     registerProject(context, { root: projectRoot });
     const project = requireProjectByRoot(context, projectRoot);
     const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot ?? projectRoot);
@@ -107,6 +111,7 @@ export function startFlowRun(context, input) {
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
+    bindCurrentEngineToRun(context, { projectRoot, runId, runHome });
     writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, 1));
     context.db.run(`INSERT INTO flow_runs
       (id, short_id, slug, project_id, project_root, workspace_root, flow_kind, subject_type, subject_id,
@@ -151,14 +156,23 @@ export function startFlowRun(context, input) {
     });
     return { ok: true, run: flowRunSummary(requireRunById(context, project.id, runId)), index };
 }
+function loadUpgradeFlowContract(context, projectRoot) {
+    const canon = resolveCanonRoot(context, context.env.DD_MEMORYBANK ? { explicitRoot: context.env.DD_MEMORYBANK } : {});
+    if (!canon.ok || !canon.canon) {
+        throw new AppError("canon_unavailable", "mb-upgrade RUN requires the pinned canonical Memory Bank", 1, {
+            project_root: projectRoot,
+            blockers: canon.blockers,
+            bootstrap: canon.bootstrap
+        });
+    }
+    return loadCanonicalFlowContract(canon.canon.flow_root);
+}
 export function getFlowRunStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    refreshRunSessionProjection(context, project.id, run.id);
-    const refreshedRun = requireRunById(context, project.id, run.id);
-    const index = authoritativeIndex(refreshedRun);
-    const runtime = readRuntimeSnapshot(refreshedRun.runtime_path);
-    return { ok: true, run: flowRunSummary(refreshedRun), index, ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, refreshedRun, index) };
+    const index = authoritativeIndex(run);
+    const runtime = readRuntimeSnapshot(run.runtime_path);
+    return { ok: true, run: flowRunSummary(run), index, ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, run, index) };
 }
 export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));

package/dist/services/schema-validation.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Ajv } from "ajv/dist/ajv.js";
 import { normalizeFlowContract } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
+import { findRunHome, readRunEngineBinding } from "./run-engine-bindings.js";
 export function captureMemoryBankBaseline(input) {
     const projectRoot = path.resolve(input.projectRoot);
     const paths = normalizeMemoryBankPaths(projectRoot, input.paths);
@@ -116,6 +117,9 @@ export function validateSchema(options) {
     };
 }
 function resolveSchema(options) {
+    const bound = resolveRunBoundSchema(options);
+    if (bound)
+        return bound;
     const fileNames = [`${options.schemaName}.schema.json`];
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
     const roots = [
@@ -145,6 +149,98 @@ function resolveSchema(options) {
         source: found.source
     };
 }
+const historicalSchemaRegistry = {
+    "294fd5f24ec6a4f938f15dfd98a4b303c2e026753062c3c6c8b15e09029a1128": [{
+            name: "merge-stage-report",
+            id: "dd-flow/merge-stage-report@2/engine-0.4.2",
+            path: "dist/schemas/merge-stage-report-legacy-0.4.2.schema.json",
+            checksum: "d861630cafd51e71e5440dadac2628413501e8b063ff19bef7d16966dc7077e3"
+        }],
+    "0fc717e17c359242662b76d8c2518bf4c4237366221e69bb979d2959d5ae8b60": [{
+            name: "merge-stage-report",
+            id: "dd-flow/stage-report@1",
+            path: "dist/schemas/stage-report.schema.json",
+            checksum: "d9889af7f2c0afb47e2abab330aea3e1750879d0738d87d38d2d20e3fe0403f3"
+        }]
+};
+function resolveRunBoundSchema(options) {
+    if (!options.projectRoot || options.schemaDir)
+        return null;
+    const data = readJson(path.resolve(options.file), "input file");
+    const root = asRecord(data);
+    const run = root ? asRecord(objectValue(root, "run")) : undefined;
+    const runId = run ? objectValue(run, "run_id") : objectValue(root ?? {}, "run_id");
+    if (typeof runId !== "string")
+        return null;
+    const projectRoot = path.resolve(options.projectRoot);
+    const located = findRunHome(options.ddFlowHome ?? process.env.DD_FLOW_HOME ?? path.join(path.dirname(projectRoot), ".dd-flow"), projectRoot, runId);
+    if (!located || !isInside(located.run_home, path.resolve(options.file)))
+        return null;
+    const binding = readRunEngineBinding(located.binding_path, { allowMissing: true });
+    if (!binding)
+        return null;
+    const manifestPath = path.join(binding.engine.snapshot_root, "engine.json");
+    const manifest = readJson(manifestPath, "bound engine manifest");
+    const integrity = asRecord(objectValue(manifest, "integrity"));
+    if (manifest.package_version !== binding.engine.package_version || manifest.engine_version !== binding.engine.engine_version || integrity?.checksum !== binding.engine.integrity_checksum) {
+        throw new AppError("run_engine_binding_invalid", "RUN engine binding does not match its engine manifest", 1, { binding: binding.engine, manifest: manifestPath });
+    }
+    const registry = asRecord(objectValue(manifest, "schema_registry"));
+    const entries = Array.isArray(registry?.entries) ? registry.entries.filter((entry) => Boolean(asRecord(entry))) : [];
+    const registered = entries.map(asSchemaRegistryEntry).find((entry) => entry?.name === options.schemaName);
+    const historical = !registered ? historicalSchemaRegistry[binding.engine.integrity_checksum]?.find((entry) => entry.name === options.schemaName) : undefined;
+    const profile = registered ?? historical;
+    if (registry && !registered) {
+        throw new AppError("schema_not_found", `Schema not registered for RUN-bound engine: ${options.schemaName}`, 2, { run_id: runId, engine: binding.engine });
+    }
+    if (!profile) {
+        throw new AppError("schema_not_found", `Schema not found for RUN-bound engine: ${options.schemaName}`, 2, { run_id: runId, engine: binding.engine });
+    }
+    const relativePath = profile.path;
+    const schemaPath = historical
+        ? path.join(bundledSchemaDir(), path.basename(relativePath))
+        : resolveInside(binding.engine.snapshot_root, relativePath);
+    if (!schemaPath || !fs.existsSync(schemaPath)) {
+        throw new AppError("schema_not_found", `Schema not found for RUN-bound engine: ${options.schemaName}`, 2, { run_id: runId, engine: binding.engine, path: relativePath });
+    }
+    if (checksum(schemaPath) !== profile.checksum) {
+        throw new AppError("schema_registry_invalid", "RUN-bound engine schema does not match its registry checksum", 1, { run_id: runId, schema: options.schemaName, path: schemaPath });
+    }
+    const schema = readJson(schemaPath, "schema");
+    const id = objectValue(asRecord(schema) ?? {}, "$id");
+    if (id !== profile.id) {
+        throw new AppError("schema_registry_invalid", "RUN-bound engine schema does not match its registry id", 1, { run_id: runId, schema: options.schemaName, path: schemaPath });
+    }
+    return {
+        name: options.schemaName,
+        id: typeof id === "string" ? id : options.schemaName,
+        path: schemaPath,
+        source: historical ? "engine_legacy_registry" : "run_bound_engine",
+        engine: { package_version: binding.engine.package_version, engine_version: binding.engine.engine_version, integrity_checksum: binding.engine.integrity_checksum, snapshot_root: binding.engine.snapshot_root }
+    };
+}
+function asSchemaRegistryEntry(value) {
+    const name = objectValue(value, "name");
+    const id = objectValue(value, "id");
+    const schemaPath = objectValue(value, "path");
+    const entryChecksum = objectValue(value, "checksum");
+    return typeof name === "string" && typeof id === "string" && typeof schemaPath === "string" && typeof entryChecksum === "string"
+        ? { name, id, path: schemaPath, checksum: entryChecksum }
+        : null;
+}
+function resolveInside(root, relativePath) {
+    if (path.isAbsolute(relativePath))
+        return null;
+    const candidate = path.resolve(root, relativePath);
+    return isInside(root, candidate) ? candidate : null;
+}
+function isInside(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function checksum(file) {
+    return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
 function bundledSchemaDir() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "schemas");
 }

package/dist/services/stage-lifecycle.js

@@ -92,6 +92,11 @@ function runtimeFacts(view, projectRoot) {
         workspace_root: view.run.workspace_root,
         run_id: view.run.id,
         protocol_id: view.run.subject.id,
+        runtime: {
+            source: "dd-flow",
+            state: "trusted",
+            flow_kind: view.run.flow_kind
+        },
         git: view.index.execution?.git ?? { branch: null, head: null, status: "unavailable" }
     };
 }
@@ -117,7 +122,9 @@ export function startStage(context, input) {
     const preflight = stagePreflight(projectRoot, stageRoot);
     if (preflight.ok !== true)
         throw new AppError("permission_preflight_failed", "Stage workspace is not writable", 1, { preflight });
-    syncProtocolLifecycle(context, attached.run.project_id, attached.run.subject.id, input.stage, "running");
+    if (attached.run.subject.type === "protocol") {
+        syncProtocolLifecycle(context, attached.run.project_id, attached.run.subject.id, input.stage, "running");
+    }
     if (input.sessionId) {
         registerFlowSession(context, {
             sessionId: input.sessionId,
@@ -143,6 +150,7 @@ export function startStage(context, input) {
     const aspectMapPath = path.join(stageRoot, "aspect-map.json");
     const attempt = attached.index.stage_runs?.find((stage) => stage.stage === input.stage)?.attempt ?? "try-001";
     const attemptNumber = Number(attempt.replace("try-", "")) || 1;
+    const sources = stageInstructionSources(context, projectRoot, attached.run.flow_kind, input.stage);
     atomicWrite(promptDataPath, {
         schema_id: "dd-flow/stage-prompt@2",
         run_id: attached.run.id,
@@ -160,10 +168,25 @@ export function startStage(context, input) {
             ...(input.stage === "plan" ? { plan: planPath, "aspect-map": aspectMapPath } : {})
         },
         write_boundary: { current: "@stage", archive: attempt, archive_writable: false },
-        source_fragments: stageInstructionSources(context, projectRoot, attached.run.flow_kind, input.stage).map((source) => source.label),
+        source_fragments: sources.map((source) => source.label),
         authoritative_facts: runtimeFacts(attached, projectRoot),
-        preflight,
-        required_context: stageInstructionSources(context, projectRoot, attached.run.flow_kind, input.stage).map((source) => source.label),
+        preflight: {
+            compatibility: {
+                status: "checked",
+                operation: `stage.${input.stage}`,
+                project_root: projectRoot
+            },
+            permissions: preflight,
+            session_binding: {
+                status: input.sessionId ? "bound" : "not_bound",
+                session_id: input.sessionId ?? null
+            }
+        },
+        required_context: sources.map((source) => ({
+            path: source.label,
+            reason: "Stage-specific canonical instruction source",
+            stop_condition: "Stop when the source no longer contains unresolved requirements for this stage"
+        })),
         worker_prompt_markdown: prompt
     });
     validateSchema({ schemaName: "stage-prompt", file: promptDataPath, projectRoot });
@@ -196,7 +219,7 @@ export function startStage(context, input) {
         },
         ...(input.stage === "plan" ? { plan_ref: planPath, aspect_map_ref: aspectMapPath } : {}),
         resolved_context: { run: attached.run, stage: { name: input.stage, dir, status: "running" } },
-        next_command: `dd-flow stage finish ${attached.run.id} --stage ${input.stage} --outcome done --project-root ${JSON.stringify(projectRoot)} --json`,
+        next_command: stageFinishCommand(attached.run, projectRoot, input.stage),
         permission_probe: preflight,
         run: attached.run,
         prompt: { path: promptPath, data_path: promptDataPath },
@@ -239,10 +262,12 @@ export function finishStage(context, input) {
     const reportPath = path.join(stageRoot, "stage-report.md");
     const htmlPath = path.join(stageRoot, "stage-report.html");
     atomicWrite(dataPath, report);
-    validateSchema({ schemaName: planFinish ? "plan-stage-report" : "stage-report", file: dataPath, projectRoot });
+    validateSchema({ schemaName: stageReportSchemaName(input.stage, planFinish), file: dataPath, projectRoot });
     atomicWrite(reportPath, renderMarkdown(report));
     atomicWrite(htmlPath, renderHtml(projectRoot, report));
-    syncProtocolLifecycle(context, view.run.project_id, view.run.subject.id, input.stage, status, stringValue(semantic.next_action));
+    if (view.run.subject.type === "protocol") {
+        syncProtocolLifecycle(context, view.run.project_id, view.run.subject.id, input.stage, status, stringValue(semantic.next_action));
+    }
     const summaryPath = updateProtocolSummary(context, projectRoot, view, report, dataPath, htmlPath, reportPath);
     const completed = completeFlowRunStage(context, {
         projectRoot,
@@ -360,6 +385,19 @@ function dataSchemaForStage(stage) {
         return "dd-flow/merge-stage-report@2";
     return "dd-flow/code-stage-report@2";
 }
+function stageReportSchemaName(stage, planFinish) {
+    if (planFinish)
+        return "plan-stage-report";
+    if (stage === "code" || stage === "implementation")
+        return "code-stage-report";
+    if (stage === "merge")
+        return "merge-stage-report";
+    return "stage-report";
+}
+function stageFinishCommand(run, projectRoot, stage) {
+    const compatibilityMode = run.flow_kind === "mb-upgrade" ? " --compatibility-mode mb-upgrade" : "";
+    return `dd-flow stage finish ${run.id} --stage ${stage} --outcome done --project-root ${JSON.stringify(projectRoot)}${compatibilityMode} --json`;
+}
 function composeStagePrompt(context, projectRoot, before, current, stage, dir, preflight) {
     const project = requireProjectByRoot(context, projectRoot);
     const runHome = runHomePath(current.run);
@@ -414,14 +452,14 @@ function composeStagePrompt(context, projectRoot, before, current, stage, dir, p
         "</work_contract>",
         "",
         "<completion_contract>",
-        `Write semantic output to \`@stage/stage-input.json\`, then run: \`dd-flow stage finish ${current.run.id} --stage ${stage} --outcome done --project-root ${JSON.stringify(projectRoot)} --json\`.`,
+        `Write semantic output to \`@stage/stage-input.json\`, then run: \`${stageFinishCommand(current.run, projectRoot, stage)}\`.`,
         "The CLI must generate validated JSON, Markdown, HTML and protocol-summary evidence.",
         "</completion_contract>",
     ].join("\n");
 }
 function stageInstructionSources(context, projectRoot, flowKind, stage) {
     if (flowKind === "mb-upgrade") {
-        const canon = resolveCanonRoot(context);
+        const canon = resolveCanonRoot(context, context.env.DD_MEMORYBANK ? { explicitRoot: context.env.DD_MEMORYBANK } : {});
         if (!canon.ok || !canon.canon) {
             throw new AppError("canon_unavailable", "mb-upgrade stage prompt requires the canonical Memory Bank", 1, {
                 blockers: canon.blockers,
@@ -541,6 +579,34 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
             }
         };
     }
+    if (stage === "code" || stage === "implementation") {
+        return {
+            schema_id: "dd-flow/code-stage-report@2",
+            run: { run_id: view.run.id, run_state: view.run.run_index_path },
+            stage: { name: stage, dir: path.basename(stageRoot), status },
+            project: { id: view.run.project_id, title: path.basename(view.run.project_root) },
+            subject: { id: view.run.subject.id, title: view.run.subject.id },
+            flow_flags: flowFlagsReportProjection(view.index.flow_flags),
+            overall: {
+                verdict: status === "done" ? "accepted" : status,
+                summary: result,
+                next_action: stringValue(semantic.next_action) ?? "Proceed to readiness."
+            },
+            breadcrumbs: [{ label: "RUN", href: view.run.run_index_path, status: "available" }],
+            implemented_goals: [{ title: `Stage ${stage}`, summary: result }],
+            acceptance_scenarios: acceptance.map((summary, index) => ({
+                id: `SCN-${stage}-${index + 1}`,
+                title: `Acceptance ${index + 1}`,
+                verdict: "accepted",
+                steps: [{ title: "Stage finish", summary }],
+                evidence: evidence.map((item) => ({ path: item, label: item }))
+            })),
+            changed_files: changedFiles.map((file) => ({ path: file, label: file })),
+            checks: checks.map((name) => ({ name, status: "passed" })),
+            review: { verdict: status === "done" ? "accepted" : status, findings: [] },
+            defs: Array.isArray(semantic.def_outcomes) ? semantic.def_outcomes : []
+        };
+    }
     return {
         schema_id: "dd-flow/stage-report@1",
         run_id: view.run.id,
@@ -611,6 +677,28 @@ function stringValue(value) {
 function stringArray(value, fallback) {
     return Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : fallback;
 }
+function flowFlagsReportProjection(value) {
+    if (!value) {
+        return {
+            flow_kind: "unknown",
+            snapshot_revision: 1,
+            resolution_status: "legacy_incomplete",
+            values: {},
+            snapshot_checksum: "0".repeat(64)
+        };
+    }
+    return {
+        ...(value.contract ? { contract: value.contract } : {}),
+        flow_kind: value.flow_kind ?? "unknown",
+        ...(value.preset ? { preset: value.preset } : {}),
+        snapshot_revision: value.snapshot_revision ?? 1,
+        resolution_status: value.resolution_status ?? "legacy_incomplete",
+        values: value.values ?? {},
+        ...(value.snapshot_checksum ? { snapshot_checksum: value.snapshot_checksum } : { snapshot_checksum: "0".repeat(64) }),
+        ...(Array.isArray(value.floors_applied) ? { floors_applied: value.floors_applied } : {}),
+        ...(value.resolved_at ? { resolved_at: value.resolved_at } : {})
+    };
+}
 function gitChangedFiles(workspaceRoot) {
     const result = spawnSync("git", ["-C", workspaceRoot, "status", "--short"], { encoding: "utf8" });
     if (result.status !== 0)
@@ -634,7 +722,7 @@ function workerCoverage(context, projectId, runId) {
 }
 function runTargetedMemoryBankLint(projectRoot, semantic) {
     const declared = stringArray(semantic.changed_files, []);
-    const files = [...new Set(declared.filter((file) => file.startsWith(".memory-bank/") && !file.split(/[\\/]/u).some((part) => part === ".." || part.startsWith(".env"))))];
+    const files = [...new Set(declared.filter((file) => file.startsWith(".memory-bank/") && file.toLowerCase().endsWith(".md") && !file.split(/[\\/]/u).some((part) => part === ".." || part.startsWith(".env"))))];
     for (const file of files)
         ensureWithin(projectRoot, path.resolve(projectRoot, file), "lint target");
     if (files.length === 0) {

package/dist/services/status.js

@@ -9,7 +9,7 @@ import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-sta
 import { findProjectByRoot } from "./projects.js";
 import { classifyCliOperation } from "./cli-operation-classifier.js";
 import { compatibilityReport } from "./compatibility-preflight.js";
-import { selectEngine } from "./engines.js";
+import { compatibilityContexts, selectEngine } from "./engines.js";
 export function getRuntimeStatus(context, input = {}) {
     const cwd = process.cwd();
     const projectRootResolution = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd });
@@ -26,9 +26,13 @@ export function getRuntimeStatus(context, input = {}) {
     const cli = getCliBuildInfo();
     const compatibilityManifest = resolvedCanonForProject ? readCompatibilityManifest(canon) : null;
     const cliCompatibility = cliCompatibilityVerdict(cli, compatibilityManifest);
-    const engineSelection = projectRoot ? selectEngine(context, { projectRoot }) : null;
+    const classification = classifyCliOperation(["status"], context.env);
+    const engineSelection = projectRoot
+        ? selectEngine(context, { projectRoot, env: context.env }, { allowCurrentInProcess: true }, classification)
+        : null;
     const flowContract = projectRoot ? projectFlowContractStatus(projectRoot) : null;
     const registry = input.checkRegistry ? checkNpmRegistry(context, cli.package_name) : undefined;
+    const contexts = projectRoot ? compatibilityContexts(context, { projectRoot, env: context.env, classification }) : null;
     return {
         ok: true,
         schema_id: "dd-flow/status-report@1",
@@ -54,7 +58,8 @@ export function getRuntimeStatus(context, input = {}) {
         engine: engineSelection
             ? {
                 selection: engineSelection,
-                compatibility: compatibilityReport(engineSelection, classifyCliOperation(["status"]))
+                compatibility: compatibilityReport(engineSelection, classification),
+                contexts
             }
             : null,
         canon: {

package/dist/storage/database.js

@@ -5,27 +5,48 @@ import { ensureDir } from "./paths.js";
 import { AppError } from "../shared/errors.js";
 const require = createRequire(import.meta.url);
 const { DatabaseSync } = require("node:sqlite");
-export function getDatabase(ddFlowHome) {
-    ensureDir(ddFlowHome);
+export function getDatabase(ddFlowHome, mode = "initialize") {
     const dbPath = path.join(ddFlowHome, "db.sqlite");
-    const db = new DatabaseSync(dbPath);
-    configureDatabase(db);
-    migrate(db);
+    const exists = fs.existsSync(dbPath);
+    if (mode === "read_existing" && !exists) {
+        return emptyReadOnlyDatabase(dbPath);
+    }
+    if (!exists || mode === "migrate")
+        ensureDir(ddFlowHome);
+    const db = mode === "read_existing" ? new DatabaseSync(dbPath, { readOnly: true }) : new DatabaseSync(dbPath);
+    configureDatabase(db, mode);
+    // Existing storage is never schema-migrated by an ordinary initialize open.
+    // Only the explicit migrate handle is allowed to execute DDL on it.
+    if (!exists || mode === "migrate")
+        migrate(db);
+    if (mode === "read_existing")
+        db.exec("PRAGMA query_only = ON");
     db.exec("PRAGMA foreign_keys = ON");
     return {
         path: dbPath,
+        writable: mode !== "read_existing",
         exec: (sql) => db.exec(sql),
         run: (sql, params = []) => db.prepare(sql).run(...params),
         get: (sql, params = []) => db.prepare(sql).get(...params),
         all: (sql, params = []) => db.prepare(sql).all(...params)
     };
 }
-function configureDatabase(db) {
-    db.exec(`
-    PRAGMA busy_timeout = 4000;
-    PRAGMA journal_mode = WAL;
-    PRAGMA synchronous = NORMAL;
-  `);
+function emptyReadOnlyDatabase(dbPath) {
+    return {
+        path: dbPath,
+        writable: false,
+        exec: () => { throw new AppError("read_only_storage", "Read-only access cannot write absent dd-flow storage", 1, { path: dbPath }); },
+        run: () => { throw new AppError("read_only_storage", "Read-only access cannot write absent dd-flow storage", 1, { path: dbPath }); },
+        get: () => undefined,
+        all: () => []
+    };
+}
+function configureDatabase(db, mode) {
+    db.exec("PRAGMA busy_timeout = 4000");
+    if (mode !== "read_existing") {
+        db.exec("PRAGMA journal_mode = WAL");
+        db.exec("PRAGMA synchronous = NORMAL");
+    }
 }
 function migrate(db) {
     db.exec(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {