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

package/dist/services/runs.js

@@ -5,17 +5,15 @@ 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 { AppError } from "../shared/errors.js";
-import { ensureDir, projectRunHome, projectRunIndexPath, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
+import { ensureDir, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { buildRunFlowGuidance } from "./flow-guidance.js";
 import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { checkpointRunUsage, usageForRun } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
-const runSchemaId = "dd-flow/flow-run-index@3";
-const legacyRunSchemaId = "dd-flow/flow-run-index@2";
-const oldestRunSchemaId = "dd-flow/flow-run-index@1";
-const runtimeSchemaId = "dd-flow/flow-run@1";
+const runSchemaId = "dd-flow/flow-run@2";
+const runtimeSchemaId = "dd-flow/flow-run@2";
 const runIdType = "RUN";
 const allowedRunFlowKinds = [
     "mb_sdlc",
@@ -51,7 +49,6 @@ export function startFlowRun(context, input) {
         now
     });
     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 = {
@@ -60,16 +57,19 @@ export function startFlowRun(context, input) {
         short_id: shortId,
         flow_kind: flowKind,
         subject: {
-            type: requiredPlain(input.subjectType, "subject-type"),
-            id: requiredPlain(input.subjectId, "subject-id")
+            id: requiredPlain(input.subjectId, "subject-id"),
+            title: requiredPlain(input.subjectId, "subject-id")
         },
         project: {
             id: project.id,
-            root: project.root
+            title: path.basename(project.root)
         },
         workspace: {
-            root: workspaceRoot,
-            run_dir: runDirRelative
+            project_root: project.root,
+            workspace_path: workspaceRoot,
+            branch: gitFacts(workspaceRoot).branch ?? "unknown",
+            base: gitFacts(workspaceRoot).head ?? "unknown",
+            manager: "official-worktrunk"
         },
         run_home: {
             storage: "dd_flow_home",
@@ -86,7 +86,7 @@ export function startFlowRun(context, input) {
         },
         stage_runs: [],
         sessions: [],
-        artifacts: [],
+        artifacts: { stage_prompt: path.join(runHome, "stage-prompt.md"), stage_report_json: path.join(runHome, "stage-report.json"), stage_report_md: path.join(runHome, "stage-report.md"), stage_report_html: path.join(runHome, "stage-report.html"), summary: path.join(runHome, "summary.md") },
         status: "running",
         verdict: "pending",
         next_action: input.nextAction ?? null,
@@ -98,12 +98,16 @@ export function startFlowRun(context, input) {
         snapshot_revision: flowFlags.snapshot_revision,
         snapshot_checksum: flowFlags.snapshot_checksum,
         reconciliation_status: "reconciled",
-        flow_flags: flowFlags
+        flow_flags: flowFlags,
+        current_stage: null,
+        attempts: [],
+        session_coverage: { status: "unavailable", expected: [], observed: [], missing: [] },
+        usage_coverage: { status: "unavailable", expected: [], observed: [], missing: [] },
+        timeline_path: "timeline.jsonl"
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
     writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, 1));
-    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, run_home_path, layout_version, artifact_root_kind,
@@ -116,14 +120,14 @@ export function startFlowRun(context, input) {
         project.root,
         workspaceRoot,
         flowKind,
-        index.subject.type,
+        requiredPlain(input.subjectType, "subject-type"),
         index.subject.id,
         index.status,
         index.verdict,
         index.next_action,
         runtimePath,
         runHome,
-        runIndexAbsolute,
+        runtimePath,
         runHome,
         "home_run_v2",
         "dd_flow_home",
@@ -152,14 +156,14 @@ export function getFlowRunStatus(context, input) {
     const run = resolveRun(context, project.id, input.runId);
     refreshRunSessionProjection(context, project.id, run.id);
     const refreshedRun = requireRunById(context, project.id, run.id);
-    const index = parseRunIndex(refreshedRun.index_json);
+    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) };
 }
 export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const runtime = readRuntimeSnapshot(run.runtime_path);
     const flags = runtime?.flow_flags ?? index.flow_flags;
     if (!flags) {
@@ -199,7 +203,7 @@ export function reviseFlowRunFlags(context, input) {
         // Read the authority only after the write lock: two callers with the same
         // expected revision must not both pass the compare-and-set check.
         const lockedRun = requireRunById(context, project.id, run.id);
-        const index = parseRunIndex(lockedRun.index_json);
+        const index = authoritativeIndex(lockedRun);
         const runtime = readRuntimeSnapshot(lockedRun.runtime_path);
         const current = runtime?.flow_flags ?? index.flow_flags;
         if (!current) {
@@ -268,7 +272,7 @@ export function reviseFlowRunFlags(context, input) {
             flow_flags: next,
             ...(reason ? { reason } : {})
         };
-        persistRunIndex(context, project, run, index, {
+        persistRunState(context, project, run, index, {
             flagRevision: { revision: next.snapshot_revision, checksum: next.snapshot_checksum, at: now, idempotency_key: idempotencyKey }
         });
         context.db.run(`INSERT INTO flow_run_flag_mutations
@@ -310,7 +314,7 @@ export function listFlowRuns(context, input) {
 export function attachFlowRunStage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const now = context.now();
     const stage = requiredPlain(input.stage, "stage");
     const dir = requiredStageDir(input.dir);
@@ -325,13 +329,20 @@ export function attachFlowRunStage(context, input) {
         dir,
         status,
         ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : existing?.data_schema_id ? { data_schema_id: existing.data_schema_id } : {}),
-        updated_at: now,
-        ...(status === "running" && !existing?.started_at ? { started_at: now } : {}),
-        ...(status === "running" ? { attempt: nextAttempt(existing) } : {})
+        updated_at: now
     };
+    if (status === "running") {
+        stageRun.started_at = now;
+        delete stageRun.completed_at;
+        stageRun.duration_ms = null;
+        stageRun.git = gitFacts(run.workspace_root);
+        stageRun.attempt = nextAttempt(existing);
+    }
     upsertStage(index, stageRun);
+    index.current_stage = stage;
+    index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
     index.updated_at = now;
-    persistRunIndex(context, project, run, index);
+    persistRunState(context, project, run, index);
     appendAudit(context, {
         projectId: project.id,
         eventType: "flow_run.stage_attached",
@@ -354,7 +365,7 @@ export function attachFlowRunStage(context, input) {
 export function completeFlowRunStage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const now = context.now();
     const stage = requiredPlain(input.stage, "stage");
     const status = parseStageStatus(input.status);
@@ -371,11 +382,20 @@ export function completeFlowRunStage(context, input) {
         ...(input.report ? { report: input.report } : {}),
         ...(input.aliases && input.aliases.length > 0 ? { artifact_aliases: input.aliases } : {}),
         updated_at: now,
-        ...(status === "done" || status === "blocked" || status === "failed" || status === "skipped" ? { completed_at: now } : {})
+        ...(status === "done" || status === "blocked" || status === "failed" || status === "skipped"
+            ? { completed_at: now, duration_ms: durationMs(existing.started_at ?? null, now), git: gitFacts(run.workspace_root) }
+            : {})
     };
     upsertStage(index, stageRun);
+    index.current_stage = stage;
+    index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
     index.updated_at = now;
-    persistRunIndex(context, project, run, index);
+    index.execution = {
+        project_root: index.execution?.project_root ?? run.project_root,
+        workspace_root: index.execution?.workspace_root ?? run.workspace_root,
+        git: gitFacts(run.workspace_root)
+    };
+    persistRunState(context, project, run, index);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, {
         projectId: project.id,
@@ -390,7 +410,7 @@ export function completeFlowRunStage(context, input) {
 export function completeFlowRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const now = context.now();
     const status = parseRunStatus(input.status);
     index.status = status;
@@ -399,8 +419,16 @@ export function completeFlowRun(context, input) {
     index.updated_at = now;
     if (["done", "blocked", "cancelled", "failed"].includes(status)) {
         index.completed_at = now;
+        index.finished_at = now;
+        index.duration_ms = durationMs(index.started_at ?? run.created_at, now);
+        index.execution = {
+            project_root: index.execution?.project_root ?? run.project_root,
+            workspace_root: index.execution?.workspace_root ?? run.workspace_root,
+            git: gitFacts(run.workspace_root)
+        };
     }
-    persistRunIndex(context, project, run, index);
+    persistRunState(context, project, run, index);
+    closeRunOrchestrators(context, project.id, run, status, now);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, {
         projectId: project.id,
@@ -412,11 +440,35 @@ export function completeFlowRun(context, input) {
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
+function closeRunOrchestrators(context, projectId, run, status, now) {
+    if (!["done", "blocked", "cancelled", "failed"].includes(status))
+        return;
+    const active = context.db.all(`SELECT session_id FROM flow_sessions
+     WHERE project_id = ? AND run_id = ? AND session_kind = 'orchestrator'
+       AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [projectId, run.id]);
+    if (active.length === 0)
+        return;
+    const reason = `run_${status}`;
+    context.db.run(`UPDATE flow_sessions SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
+     WHERE project_id = ? AND run_id = ? AND session_kind = 'orchestrator'
+       AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [reason, now, now, projectId, run.id]);
+    context.db.run(`UPDATE flow_session_segments SET ended_at = ?
+     WHERE project_id = ? AND run_id = ? AND session_id IN (${active.map(() => "?").join(", ")}) AND ended_at IS NULL`, [now, projectId, run.id, ...active.map((session) => session.session_id)]);
+    for (const session of active) {
+        appendRunTimeline(runArtifactRoot(run), {
+            at: now,
+            type: "session_stopped",
+            run_id: run.id,
+            session_id: session.session_id,
+            reason
+        });
+    }
+}
 const timelineSections = ["stages", "events", "sessions", "usage", "artifacts"];
 export function getFlowRunTimeline(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const file = path.join(runArtifactRoot(run), "timeline.jsonl");
     const events = fs.existsSync(file)
         ? fs.readFileSync(file, "utf8").split(/\r?\n/).flatMap((line) => { try {
@@ -426,7 +478,10 @@ export function getFlowRunTimeline(context, input) {
             return [];
         } })
         : [];
-    const hidden = parseHiddenTimelineSections(input.hiddenSections ?? []);
+    if ((input.hiddenSections ?? []).length > 0) {
+        throw new AppError("validation", "Timeline sections are always included", 2, { hidden_sections: input.hiddenSections });
+    }
+    const hidden = new Set();
     const sessions = index.sessions;
     const elapsedMs = durationMs(index.started_at ?? run.created_at, index.completed_at ?? null);
     const report = {
@@ -481,6 +536,14 @@ export function appendFlowRunTimelineEvent(context, projectId, runId, event) {
     appendRunTimeline(runArtifactRoot(run), { run_id: run.id, ...event });
 }
 function guidanceForRun(context, run, index) {
+    if (run.status === "discarded") {
+        return buildRunFlowGuidance({
+            stageRuns: index.stage_runs,
+            protocolStage: "cancelled",
+            runId: run.id,
+            runDir: index.run_home?.relative_path ?? path.posix.join("runs", run.id)
+        });
+    }
     if (run.subject_type === "protocol") {
         try {
             const protocol = requireProtocol(context, run.subject_id, run.project_id);
@@ -490,7 +553,7 @@ function guidanceForRun(context, run, index) {
                 protocolStage: state.stage,
                 ...(state.flow_contract ? { contract: state.flow_contract } : {}),
                 runId: run.id,
-                runDir: index.run_home?.relative_path ?? index.workspace.run_dir
+                runDir: index.run_home?.relative_path ?? path.posix.join("runs", run.id)
             });
         }
         catch (error) {
@@ -498,11 +561,10 @@ function guidanceForRun(context, run, index) {
                 throw error;
         }
     }
-    return buildRunFlowGuidance({ stageRuns: index.stage_runs, runId: run.id, runDir: index.run_home?.relative_path ?? index.workspace.run_dir });
+    return buildRunFlowGuidance({ stageRuns: index.stage_runs, runId: run.id, runDir: index.run_home?.relative_path ?? path.posix.join("runs", run.id) });
 }
-function persistRunIndex(context, project, run, index, options = {}) {
+function persistRunState(context, project, run, index, options = {}) {
     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);
     const previousRuntime = readRuntimeSnapshot(runtimePath);
     const runtimeRevision = Math.max(index.runtime_revision ?? 0, previousRuntime?.runtime_revision ?? 0) + 1;
     index.runtime_revision = runtimeRevision;
@@ -511,9 +573,7 @@ function persistRunIndex(context, project, run, index, options = {}) {
         history.push(options.flagRevision);
     }
     ensureDir(path.dirname(runtimePath));
-    ensureDir(path.dirname(runIndexPath));
     writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, runtimeRevision, history));
-    writeJsonFile(runIndexPath, index);
     context.db.run(`UPDATE flow_runs
      SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?,
        updated_at = ?, completed_at = ?
@@ -523,7 +583,7 @@ function persistRunIndex(context, project, run, index, options = {}) {
         index.next_action,
         JSON.stringify(index),
         runtimePath,
-        runIndexPath,
+        runtimePath,
         index.updated_at,
         index.completed_at ?? null,
         project.id,
@@ -539,10 +599,12 @@ function appendRunTimeline(runHome, event) {
         const last = lines.length > 0 ? JSON.parse(lines[lines.length - 1]) : undefined;
         sequence = typeof last?.sequence === "number" ? last.sequence : lines.length;
     }
+    const safeEvent = sanitizeTimelineValue(event);
     const enriched = {
         event_id: crypto.randomUUID(),
         sequence: sequence + 1,
-        ...event
+        at: typeof safeEvent.at === "string" ? safeEvent.at : new Date().toISOString(),
+        ...safeEvent
     };
     fs.appendFileSync(timelinePath, `${JSON.stringify(enriched)}\n`);
 }
@@ -552,7 +614,6 @@ function runtimeSnapshotForIndex(index, runtimeRevision, flagRevisionHistory = [
     return {
         ...rest,
         schema_id: runtimeSchemaId,
-        run_index_schema_id: index.schema_id,
         runtime_revision: runtimeRevision,
         ...(flagRevisionHistory.length > 0 ? { flag_revision_history: flagRevisionHistory.slice(-32) } : {})
     };
@@ -568,18 +629,26 @@ function readRuntimeSnapshot(file) {
         return undefined;
     }
 }
-function parseHiddenTimelineSections(values) {
-    const hidden = new Set();
-    for (const value of values) {
-        if (!timelineSections.includes(value)) {
-            throw new AppError("validation", "--hide must name a timeline section", 2, {
-                value,
-                allowed: timelineSections
-            });
-        }
-        hidden.add(value);
+function authoritativeIndex(run) {
+    const runtime = readRuntimeSnapshot(run.runtime_path);
+    if (!runtime) {
+        throw new AppError("validation", "RUN authority is missing or invalid", 2, { run_id: run.id, path: run.runtime_path });
+    }
+    return { ...runtime, schema_id: runSchemaId };
+}
+function sanitizeTimelineValue(value, key) {
+    if (key && /(secret|password|authorization|cookie|api[_-]?key|private[_-]?key|access[_-]?token|refresh[_-]?token|transcript|prompt|tool[_-]?output|document[_-]?content)/i.test(key)) {
+        return "[REDACTED]";
+    }
+    if (typeof value === "string") {
+        return value.length > 512 ? `${value.slice(0, 512)}…[TRUNCATED]` : value;
     }
-    return hidden;
+    if (Array.isArray(value))
+        return value.map((item) => sanitizeTimelineValue(item));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([entryKey, entryValue]) => [entryKey, sanitizeTimelineValue(entryValue, entryKey)]));
+    }
+    return value;
 }
 function durationMs(startedAt, completedAt) {
     if (!startedAt || !completedAt)
@@ -669,13 +738,6 @@ function flowRunSummary(run) {
         completed_at: run.completed_at
     };
 }
-function parseRunIndex(text) {
-    const index = JSON.parse(text);
-    if (index.schema_id !== runSchemaId && index.schema_id !== legacyRunSchemaId && index.schema_id !== oldestRunSchemaId) {
-        throw new AppError("validation", `Invalid run index schema: ${String(index.schema_id)}`, 2);
-    }
-    return index;
-}
 function parseRunFlowKind(value) {
     const normalized = value === "mb-sdlc" ? "mb_sdlc" : value;
     if (!allowedRunFlowKinds.includes(normalized)) {
@@ -763,12 +825,17 @@ function writeJsonFile(file, value) {
     fs.renameSync(tmpFile, file);
 }
 function runArtifactRoot(run) {
-    return path.dirname(run.run_index_path);
+    return run.run_home_path ?? path.dirname(run.runtime_path);
 }
 function gitFacts(workspaceRoot) {
     const read = (args) => {
         const result = spawnSync("git", ["-C", workspaceRoot, ...args.split(" ")], { encoding: "utf8" });
         return result.status === 0 ? result.stdout.trim() || null : null;
     };
-    return { branch: read("branch --show-current"), head: read("rev-parse HEAD") };
+    const status = read("status --porcelain --untracked-files=all");
+    return {
+        branch: read("branch --show-current"),
+        head: read("rev-parse HEAD"),
+        status: status === null ? "unavailable" : status.length > 0 ? "dirty" : "clean"
+    };
 }

package/dist/services/schema-validation.js

@@ -1,9 +1,65 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 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";
+export function captureMemoryBankBaseline(input) {
+    const projectRoot = path.resolve(input.projectRoot);
+    const paths = normalizeMemoryBankPaths(projectRoot, input.paths);
+    if (paths.length === 0) {
+        throw new AppError("validation", "Memory Bank baseline requires at least one exact target path", 2);
+    }
+    return {
+        schema_id: "dd-flow/memory-bank-baseline@1",
+        project_root: projectRoot,
+        paths: Object.fromEntries(paths.map((relativePath) => [relativePath, snapshotMemoryBankPath(projectRoot, relativePath)]))
+    };
+}
+export function validateMemoryBankDelta(input) {
+    const projectRoot = path.resolve(input.projectRoot);
+    if (input.baseline.schema_id !== "dd-flow/memory-bank-baseline@1" || path.resolve(input.baseline.project_root) !== projectRoot) {
+        throw new AppError("validation", "Memory Bank baseline does not belong to this project root", 2, {
+            baseline_root: input.baseline.project_root,
+            project_root: projectRoot
+        });
+    }
+    const paths = normalizeMemoryBankPaths(projectRoot, Object.keys(input.baseline.paths));
+    if (paths.length === 0) {
+        throw new AppError("validation", "Memory Bank baseline has no exact target paths", 2);
+    }
+    const after = Object.fromEntries(paths.map((relativePath) => [relativePath, snapshotMemoryBankPath(projectRoot, relativePath)]));
+    const snapshots = paths.map((relativePath) => {
+        const before = input.baseline.paths[relativePath];
+        const current = after[relativePath];
+        if (!before || !current) {
+            throw new AppError("validation", `Memory Bank baseline snapshot is incomplete: ${relativePath}`, 2);
+        }
+        return { relativePath, before, after: current };
+    });
+    const changedSnapshots = snapshots.filter(({ before, after: current }) => !sameMemoryBankSnapshot(before, current));
+    const changed = changedSnapshots.map(({ relativePath }) => relativePath);
+    const added = changedSnapshots.filter(({ before, after: current }) => !before.exists && current.exists).map(({ relativePath }) => relativePath);
+    const removed = changedSnapshots.filter(({ before, after: current }) => before.exists && !current.exists).map(({ relativePath }) => relativePath);
+    const findings = [];
+    for (const { relativePath, after: snapshot } of changedSnapshots) {
+        if (!snapshot.exists) {
+            findings.push({ path: relativePath, severity: "error", code: "deleted_target", message: "Tracked Memory Bank target was deleted" });
+            continue;
+        }
+        findings.push(...validateChangedMemoryFile(projectRoot, relativePath));
+    }
+    return {
+        schema_id: "dd-flow/memory-bank-delta-validation@1",
+        ok: findings.length === 0,
+        project_root: projectRoot,
+        checked_paths: paths,
+        baseline: input.baseline.paths,
+        delta: { changed, added, removed },
+        findings
+    };
+}
 const schemaNamePattern = /^[a-z0-9][a-z0-9-]*$/;
 const mandatoryMbUpgradeReviewAspectIds = [
     "01-goal-and-delivery",
@@ -37,7 +93,7 @@ export function validateSchema(options) {
     }
     const filePath = path.resolve(options.file);
     const data = readJson(filePath, "input file");
-    const schemaResolution = resolveSchema(options, data);
+    const schemaResolution = resolveSchema(options);
     const schema = readJson(schemaResolution.path, "schema");
     const ajv = new Ajv({ allErrors: true, strict: false, validateFormats: false });
     const validate = ajv.compile(schema);
@@ -59,12 +115,8 @@ export function validateSchema(options) {
         errors: []
     };
 }
-function resolveSchema(options, data) {
-    const dataRecord = asRecord(data);
-    const dataSchemaId = dataRecord ? stringValue(dataRecord, "schema_id") : undefined;
-    const fileNames = options.schemaName === "flow-run-index" && dataSchemaId === "dd-flow/flow-run-index@3"
-        ? ["flow-run-index-v3.schema.json", "flow-run-index.schema.json"]
-        : [`${options.schemaName}.schema.json`];
+function resolveSchema(options) {
+    const fileNames = [`${options.schemaName}.schema.json`];
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
     const roots = [
         ...(options.schemaDir ? [{ directory: path.resolve(options.schemaDir), source: "schema_dir" }] : []),
@@ -262,6 +314,115 @@ function validateMbSdlcReviewReport(root) {
     });
     return errors;
 }
+function normalizeMemoryBankPaths(projectRoot, inputs) {
+    return [...new Set(inputs.map((input) => {
+            const absolute = resolveMemoryBankPath(projectRoot, input);
+            const relative = path.relative(projectRoot, absolute);
+            if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+                throw new AppError("validation", "Memory Bank target must remain inside project root", 2, { target: input });
+            }
+            return relative;
+        }))].sort();
+}
+function resolveMemoryBankPath(projectRoot, input) {
+    const absolute = path.isAbsolute(input) ? path.resolve(input) : path.resolve(projectRoot, input);
+    const relative = path.relative(projectRoot, absolute);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new AppError("validation", "Memory Bank target must remain inside project root", 2, { target: input });
+    }
+    const existing = nearestExistingPath(absolute);
+    if (existing) {
+        const realRoot = fs.realpathSync(projectRoot);
+        const realExisting = fs.realpathSync(existing);
+        const realResolved = path.resolve(realExisting, path.relative(existing, absolute));
+        const realRelative = path.relative(realRoot, realResolved);
+        if (realRelative.startsWith("..") || path.isAbsolute(realRelative)) {
+            throw new AppError("validation", "Memory Bank target escapes project root through a symlink", 2, { target: input });
+        }
+    }
+    return absolute;
+}
+function nearestExistingPath(target) {
+    let current = target;
+    while (!fs.existsSync(current)) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return current;
+}
+function snapshotMemoryBankPath(projectRoot, relativePath) {
+    const absolute = resolveMemoryBankPath(projectRoot, relativePath);
+    if (!fs.existsSync(absolute))
+        return { exists: false, bytes: null, sha256: null };
+    let stat;
+    let content;
+    try {
+        stat = fs.statSync(absolute);
+        if (!stat.isFile())
+            throw new Error("target is not a file");
+        content = fs.readFileSync(absolute);
+    }
+    catch (error) {
+        throw new AppError("validation", `Cannot snapshot Memory Bank target: ${relativePath}`, 2, { cause: String(error) });
+    }
+    return {
+        exists: true,
+        bytes: content.byteLength,
+        sha256: crypto.createHash("sha256").update(content).digest("hex")
+    };
+}
+function sameMemoryBankSnapshot(before, after) {
+    return Boolean(before)
+        && before?.exists === after.exists
+        && before?.bytes === after.bytes
+        && before?.sha256 === after.sha256;
+}
+function validateChangedMemoryFile(projectRoot, relativePath) {
+    const absolute = resolveMemoryBankPath(projectRoot, relativePath);
+    let content;
+    try {
+        content = fs.readFileSync(absolute, "utf8");
+    }
+    catch (error) {
+        return [{ path: relativePath, severity: "error", code: "unreadable_target", message: String(error) }];
+    }
+    const findings = [];
+    if (path.extname(relativePath).toLowerCase() === ".json") {
+        try {
+            JSON.parse(content);
+        }
+        catch (error) {
+            findings.push({ path: relativePath, severity: "error", code: "invalid_json", message: String(error) });
+        }
+    }
+    const markdownLinkPattern = /\]\((<[^>]+>|[^)\s]+)(?:\s+["'][^)]*["'])?\)/g;
+    for (const match of content.matchAll(markdownLinkPattern)) {
+        const capturedTarget = match[1];
+        if (!capturedTarget)
+            continue;
+        const rawTarget = capturedTarget.replace(/^<|>$/g, "");
+        if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(rawTarget))
+            continue;
+        const linkTarget = rawTarget.split(/[?#]/, 1)[0];
+        if (!linkTarget)
+            continue;
+        let resolved;
+        try {
+            const linkedAbsolute = path.resolve(path.dirname(path.join(projectRoot, relativePath)), linkTarget);
+            resolved = resolveMemoryBankPath(projectRoot, path.relative(projectRoot, linkedAbsolute));
+        }
+        catch (error) {
+            findings.push({ path: relativePath, severity: "error", code: "path_escape", message: String(error) });
+            continue;
+        }
+        if (!fs.existsSync(resolved)) {
+            findings.push({ path: relativePath, severity: "error", code: "missing_link", message: `Linked path does not exist: ${linkTarget}` });
+        }
+    }
+    return findings;
+}
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
 }