@danielblomma/cortex-mcp 2.0.8 → 2.0.12

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.8",
+  "version": "2.0.12",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",

package/scaffold/mcp/package.json

@@ -9,7 +9,8 @@
     "graph:load": "npm run build --silent && node dist/loadGraph.js",
     "dev": "node --loader ts-node/esm src/server.ts",
     "start": "node dist/server.js",
-    "test": "npm run build --silent && node --test tests/*.test.mjs"
+    "test": "npm run build --silent && node --test tests/*.test.mjs",
+    "test:ci": "npm run build --silent && node --test --test-reporter=spec tests/*.test.mjs"
   },
   "dependencies": {
     "@huggingface/transformers": "^4.1.0",

package/scaffold/mcp/src/core/workflow/enforcement.ts

@@ -4,6 +4,7 @@ import { readRunState } from "./artifact-io.js";
 import { DEFAULT_CAPABILITIES, type CapabilityDefinition } from "./capabilities.js";
 import { workflowDefinitionSchema, type WorkflowDefinition } from "./schemas.js";
 import { DEFAULT_WORKFLOWS } from "./default-workflows.js";
+import { loadSyncedCapabilities } from "./synced-capability-registry.js";
 
 /**
  * Pre-tool-use enforcement for the harness. Pure function: takes the tool
@@ -83,7 +84,12 @@ export function evaluateToolCall(options: EvaluateOptions): EnforcementResult {
     return { allowed: true, reason: "stage has no capability declared" };
   }
 
-  const capabilities = options.capabilities ?? DEFAULT_CAPABILITIES;
+  // When the caller passes an explicit registry, use it as-is (tests).
+  // Otherwise merge bundled defaults with the daemon-synced org-authored
+  // capabilities, with synced ones taking precedence on name collisions
+  // so org overrides actually override.
+  const capabilities =
+    options.capabilities ?? { ...DEFAULT_CAPABILITIES, ...loadSyncedCapabilities() };
   const capability = capabilities[stage.capability];
   if (!capability) {
     return {

package/scaffold/mcp/src/core/workflow/index.ts

@@ -7,3 +7,4 @@ export * from "./mcp-tools.js";
 export * from "./capabilities.js";
 export * from "./enforcement.js";
 export * from "./synced-registry.js";
+export * from "./synced-capability-registry.js";

package/scaffold/mcp/src/core/workflow/synced-capability-registry.ts

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  capabilityDefinitionSchema,
+  type CapabilityDefinition,
+} from "./capabilities.js";
+
+/**
+ * Read side of the org-capability sync cache. The daemon's
+ * capability-sync-checker writes ~/.cortex/capabilities.local.json;
+ * this module reads it. Kept in core/workflow/ rather than daemon/ so
+ * enforcement.ts can consult the cache without depending on daemon code.
+ *
+ * Each entry is validated against capabilityDefinitionSchema before being
+ * surfaced — if the cache file is corrupt or contains stale shapes from
+ * an older daemon, those entries are silently dropped rather than
+ * crashing the read.
+ */
+
+export const SYNCED_CAPABILITIES_FILENAME = "capabilities.local.json";
+
+type LocalCapabilityRecord = {
+  capability_name: string;
+  updated_at: string;
+  definition: unknown;
+};
+
+type LocalCapabilitiesState = {
+  capabilities?: Record<string, LocalCapabilityRecord>;
+};
+
+export function syncedCapabilitiesCachePath(dir?: string): string {
+  return join(dir ?? join(homedir(), ".cortex"), SYNCED_CAPABILITIES_FILENAME);
+}
+
+/**
+ * Returns the synced org-authored capabilities keyed by capability name.
+ * Empty object when the cache is missing, unreadable, malformed, or
+ * contains no valid entries. The optional `dir` argument is for tests;
+ * production callers leave it unset.
+ */
+export function loadSyncedCapabilities(
+  dir?: string,
+): Record<string, CapabilityDefinition> {
+  const path = syncedCapabilitiesCachePath(dir);
+  if (!existsSync(path)) return {};
+
+  let parsed: LocalCapabilitiesState;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8")) as LocalCapabilitiesState;
+  } catch {
+    return {};
+  }
+  const records = parsed.capabilities;
+  if (!records || typeof records !== "object") return {};
+
+  const out: Record<string, CapabilityDefinition> = {};
+  for (const [name, record] of Object.entries(records)) {
+    if (!record || typeof record !== "object") continue;
+    const result = capabilityDefinitionSchema.safeParse(record.definition);
+    if (!result.success) continue;
+    out[name] = result.data;
+  }
+  return out;
+}

package/scaffold/mcp/src/daemon/capability-sync-checker.ts

@@ -0,0 +1,295 @@
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { loadEnterpriseConfig } from "../core/config.js";
+import {
+  capabilityDefinitionSchema,
+  type CapabilityDefinition,
+} from "../core/workflow/capabilities.js";
+import { writeHostAuditEvent } from "./ungoverned-scanner.js";
+import { daemonDir } from "./paths.js";
+
+/**
+ * Org-capability sync flow — daemon side.
+ *
+ * The daemon polls cortex-web /api/v1/govern/capabilities/manifest each
+ * tick to learn what capabilities the org has authored. It diffs against
+ * a local state file, fetches changed full definitions, and caches them
+ * locally. The pre-tool-use hook's evaluateToolCall consults the merged
+ * registry via loadSyncedCapabilities() with synced taking precedence
+ * over bundled DEFAULT_CAPABILITIES on name collisions.
+ *
+ * Three audit outcomes per tick:
+ *  - capabilities_unchanged   — manifest matches local state
+ *  - capabilities_synced      — at least one capability was added /
+ *                               changed / removed (metadata: counts)
+ *  - capabilities_sync_failed — network / auth / parse error
+ */
+
+const STATE_FILENAME = "capabilities.local.json";
+
+type ManifestEntry = {
+  capability_name: string;
+  updated_at: string;
+};
+
+type FetchedCapability = {
+  capability_name: string;
+  description: string;
+  definition: CapabilityDefinition;
+  updated_at: string;
+};
+
+type LocalCapabilityRecord = {
+  capability_name: string;
+  updated_at: string;
+  definition: CapabilityDefinition;
+};
+
+type LocalCapabilitiesState = {
+  capabilities: Record<string, LocalCapabilityRecord>;
+  last_synced_at?: string;
+};
+
+export type CapabilitySyncOutcome =
+  | { kind: "unchanged"; count: number }
+  | {
+      kind: "synced";
+      added: string[];
+      changed: string[];
+      removed: string[];
+    }
+  | { kind: "failed"; error: string };
+
+function stateFilePath(): string {
+  return join(daemonDir(), STATE_FILENAME);
+}
+
+function readSyncedCapabilitiesState(): LocalCapabilitiesState {
+  const path = stateFilePath();
+  if (!existsSync(path)) return { capabilities: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as LocalCapabilitiesState;
+    return {
+      capabilities: parsed.capabilities ?? {},
+      last_synced_at: parsed.last_synced_at,
+    };
+  } catch {
+    return { capabilities: {} };
+  }
+}
+
+function writeSyncedCapabilitiesState(state: LocalCapabilitiesState): void {
+  writeFileSync(
+    stateFilePath(),
+    JSON.stringify(state, null, 2) + "\n",
+    "utf8",
+  );
+}
+
+async function fetchManifest(
+  baseUrl: string,
+  apiKey: string,
+): Promise<ManifestEntry[]> {
+  const url = new URL(
+    baseUrl.replace(/\/$/, "") + "/api/v1/govern/capabilities/manifest",
+  );
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  }
+  const body = (await res.json()) as { capabilities?: ManifestEntry[] };
+  return body.capabilities ?? [];
+}
+
+async function fetchCapability(
+  baseUrl: string,
+  apiKey: string,
+  capabilityName: string,
+): Promise<FetchedCapability> {
+  const url = new URL(
+    baseUrl.replace(/\/$/, "") +
+      "/api/v1/govern/capabilities/" +
+      encodeURIComponent(capabilityName),
+  );
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  }
+  const body = (await res.json()) as { capability?: FetchedCapability };
+  if (!body.capability) {
+    throw new Error(`Response for ${capabilityName} missing 'capability' field`);
+  }
+  return body.capability;
+}
+
+export async function runCapabilitySyncOnce(
+  cwd: string,
+): Promise<CapabilitySyncOutcome> {
+  const config = loadEnterpriseConfig(join(cwd, ".context"));
+  const apiKey = config.enterprise.api_key.trim();
+  const baseUrl = (config.enterprise.base_url || config.enterprise.endpoint).trim();
+  if (!apiKey || !baseUrl) {
+    const outcome: CapabilitySyncOutcome = {
+      kind: "failed",
+      error: "enterprise not configured",
+    };
+    await writeAudit(cwd, outcome);
+    return outcome;
+  }
+
+  let manifest: ManifestEntry[];
+  try {
+    manifest = await fetchManifest(baseUrl, apiKey);
+  } catch (err) {
+    const outcome: CapabilitySyncOutcome = {
+      kind: "failed",
+      error: err instanceof Error ? err.message : String(err),
+    };
+    await writeAudit(cwd, outcome);
+    return outcome;
+  }
+
+  const state = readSyncedCapabilitiesState();
+  const remoteByName = new Map(manifest.map((e) => [e.capability_name, e]));
+
+  const added: string[] = [];
+  const changed: string[] = [];
+  const removed: string[] = [];
+
+  for (const entry of manifest) {
+    const local = state.capabilities[entry.capability_name];
+    const isNew = !local;
+    const isChanged =
+      Boolean(local) && local.updated_at !== entry.updated_at;
+    if (!isNew && !isChanged) continue;
+
+    let fetched: FetchedCapability;
+    try {
+      fetched = await fetchCapability(baseUrl, apiKey, entry.capability_name);
+    } catch (err) {
+      const outcome: CapabilitySyncOutcome = {
+        kind: "failed",
+        error:
+          err instanceof Error
+            ? `fetch ${entry.capability_name}: ${err.message}`
+            : `fetch ${entry.capability_name}: ${String(err)}`,
+      };
+      await writeAudit(cwd, outcome);
+      return outcome;
+    }
+
+    let validated: CapabilityDefinition;
+    try {
+      validated = capabilityDefinitionSchema.parse(fetched.definition);
+    } catch (err) {
+      const outcome: CapabilitySyncOutcome = {
+        kind: "failed",
+        error:
+          err instanceof Error
+            ? `validate ${entry.capability_name}: ${err.message}`
+            : `validate ${entry.capability_name}: ${String(err)}`,
+      };
+      await writeAudit(cwd, outcome);
+      return outcome;
+    }
+
+    state.capabilities[entry.capability_name] = {
+      capability_name: entry.capability_name,
+      updated_at: fetched.updated_at,
+      definition: validated,
+    };
+    (isNew ? added : changed).push(entry.capability_name);
+  }
+
+  for (const name of Object.keys(state.capabilities)) {
+    if (remoteByName.has(name)) continue;
+    delete state.capabilities[name];
+    removed.push(name);
+  }
+
+  const totalChanged = added.length + changed.length + removed.length;
+  if (totalChanged === 0) {
+    const outcome: CapabilitySyncOutcome = {
+      kind: "unchanged",
+      count: manifest.length,
+    };
+    await writeAudit(cwd, outcome);
+    return outcome;
+  }
+
+  state.last_synced_at = new Date().toISOString();
+  writeSyncedCapabilitiesState(state);
+  const outcome: CapabilitySyncOutcome = {
+    kind: "synced",
+    added,
+    changed,
+    removed,
+  };
+  await writeAudit(cwd, outcome);
+  return outcome;
+}
+
+async function writeAudit(cwd: string, outcome: CapabilitySyncOutcome): Promise<void> {
+  const eventBase = {
+    timestamp: new Date().toISOString(),
+    host_id: hostname(),
+  };
+  if (outcome.kind === "unchanged") {
+    await writeHostAuditEvent(cwd, {
+      ...eventBase,
+      event_type: "capabilities_unchanged",
+      count: outcome.count,
+    }).catch(() => undefined);
+  } else if (outcome.kind === "synced") {
+    await writeHostAuditEvent(cwd, {
+      ...eventBase,
+      event_type: "capabilities_synced",
+      added: outcome.added,
+      changed: outcome.changed,
+      removed: outcome.removed,
+    }).catch(() => undefined);
+  } else {
+    await writeHostAuditEvent(cwd, {
+      ...eventBase,
+      event_type: "capabilities_sync_failed",
+      error: outcome.error,
+    }).catch(() => undefined);
+  }
+}
+
+export type CapabilitySyncTimerHandle = {
+  stop(): void;
+};
+
+export function startCapabilitySyncTimer(
+  cwd: string,
+  intervalMs: number,
+): CapabilitySyncTimerHandle {
+  const tick = () => {
+    void runCapabilitySyncOnce(cwd).catch((err) => {
+      process.stderr.write(
+        `[cortex-daemon] capability sync failed: ${
+          err instanceof Error ? err.message : String(err)
+        }\n`,
+      );
+    });
+  };
+
+  void Promise.resolve().then(tick);
+  const handle = setInterval(tick, intervalMs);
+  if (typeof handle.unref === "function") handle.unref();
+  return {
+    stop() {
+      clearInterval(handle);
+    },
+  };
+}

package/scaffold/mcp/src/daemon/main.ts

@@ -29,6 +29,7 @@ import {
 import { startSyncTimer } from "./sync-checker.js";
 import { startSkillSyncTimer } from "./skill-sync-checker.js";
 import { startWorkflowSyncTimer } from "./workflow-sync-checker.js";
+import { startCapabilitySyncTimer } from "./capability-sync-checker.js";
 import { startHostEventsPusher } from "./host-events-pusher.js";
 import { startEgressProxy } from "./egress-proxy.js";
 import { startHeartbeatPusher } from "./heartbeat-pusher.js";
@@ -372,6 +373,20 @@ async function main(): Promise<void> {
     startWorkflowSyncTimer(process.cwd(), workflowSyncMs);
   }
 
+  // Harness Phase 2: poll cortex-web for org-authored capabilities and
+  // cache definitions locally so evaluateToolCall can merge them over
+  // bundled DEFAULT_CAPABILITIES on the pre-tool-use path. Same cadence
+  // as the workflow sync by default; independently configurable via
+  // CORTEX_CAPABILITY_SYNC_MS / CORTEX_DISABLE_CAPABILITY_SYNC.
+  const capabilitySyncRaw = parseInt(process.env.CORTEX_CAPABILITY_SYNC_MS ?? "", 10);
+  const capabilitySyncMs =
+    Number.isFinite(capabilitySyncRaw) && capabilitySyncRaw > 0
+      ? capabilitySyncRaw
+      : workflowSyncMs;
+  if (process.env.CORTEX_DISABLE_CAPABILITY_SYNC !== "1") {
+    startCapabilitySyncTimer(process.cwd(), capabilitySyncMs);
+  }
+
   // Govern host heartbeat — fills host_enrollment on cortex-web so the
   // dashboard at /dashboard/govern actually shows this host.
   const heartbeatRaw = parseInt(process.env.CORTEX_HEARTBEAT_PUSH_MS ?? "", 10);

package/scaffold/mcp/src/embed.ts

@@ -1,20 +1,15 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { env, pipeline } from "@huggingface/transformers";
 import { readJsonl, asString, asNumber, asBoolean } from "./jsonl.js";
+import { CACHE_DIR, PATHS } from "./paths.js";
 import type { JsonObject, JsonValue } from "./types.js";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const REPO_ROOT = path.resolve(__dirname, "../..");
-const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
-const CACHE_DIR = path.join(CONTEXT_DIR, "cache");
-const EMBEDDINGS_DIR = path.join(CONTEXT_DIR, "embeddings");
-const EMBEDDINGS_PATH = path.join(EMBEDDINGS_DIR, "entities.jsonl");
-const EMBEDDINGS_MANIFEST_PATH = path.join(EMBEDDINGS_DIR, "manifest.json");
-const MODEL_CACHE_DIR = path.join(EMBEDDINGS_DIR, "models");
+const EMBEDDINGS_PATH = PATHS.embeddingsEntities;
+const EMBEDDINGS_MANIFEST_PATH = PATHS.embeddingsManifest;
+const MODEL_CACHE_DIR = PATHS.embeddingsModelCache;
+const EMBEDDINGS_DIR = path.dirname(EMBEDDINGS_PATH);
 
 const DEFAULT_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
 const DEFAULT_MAX_TEXT_CHARS = 7000;

package/scaffold/mcp/src/loadGraph.ts

@@ -1,16 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import ryugraph, { type Connection, type PreparedStatement, type QueryResult, type RyuValue } from "ryugraph";
 import { readJsonl, asString, asNumber, asBoolean } from "./jsonl.js";
+import { CACHE_DIR, CONTEXT_DIR, DB_PATH } from "./paths.js";
 import type { JsonObject } from "./types.js";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const REPO_ROOT = path.resolve(__dirname, "../..");
-const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
-const CACHE_DIR = path.join(CONTEXT_DIR, "cache");
-const DB_PATH = path.join(CONTEXT_DIR, "db", "graph.ryu");
 const ONTOLOGY_PATH = path.join(CONTEXT_DIR, "ontology.cypher");
 const BATCH_SIZE = 50;
 

package/scaffold/mcp/src/paths.ts

@@ -21,9 +21,45 @@ function normalizeForWsl(rawPath: string): string {
 }
 
 const PROJECT_ROOT_OVERRIDE = process.env.CORTEX_PROJECT_ROOT?.trim();
-export const REPO_ROOT = PROJECT_ROOT_OVERRIDE
-  ? path.resolve(normalizeForWsl(PROJECT_ROOT_OVERRIDE))
-  : path.resolve(__dirname, "../..");
+
+function hasContextConfig(candidate: string): boolean {
+  return fs.existsSync(path.join(candidate, ".context", "config.yaml"));
+}
+
+function resolveFrom(startDir: string): string | null {
+  let current = path.resolve(startDir);
+  while (true) {
+    if (hasContextConfig(current)) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function resolveRepoRoot(): string {
+  const candidates = [
+    PROJECT_ROOT_OVERRIDE ? path.resolve(normalizeForWsl(PROJECT_ROOT_OVERRIDE)) : null,
+    process.cwd(),
+    __dirname,
+    process.env.INIT_CWD?.trim() ? path.resolve(normalizeForWsl(process.env.INIT_CWD.trim())) : null
+  ].filter((value): value is string => Boolean(value));
+
+  for (const candidate of candidates) {
+    const resolved = resolveFrom(candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  return path.resolve(__dirname, "../../..");
+}
+
+export const REPO_ROOT = resolveRepoRoot();
 export const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
 export const CACHE_DIR = path.join(CONTEXT_DIR, "cache");
 export const DB_PATH = path.join(CONTEXT_DIR, "db", "graph.ryu");

package/scaffold/mcp/tests/paths.test.mjs

@@ -0,0 +1,38 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+test("paths resolve the project root from cwd without duplicating .context", () => {
+  const projectRoot = mkdtempSync(path.join(tmpdir(), "cortex-paths-"));
+  const contextDir = path.join(projectRoot, ".context");
+  const mcpDir = path.join(contextDir, "mcp");
+  const pathsModuleUrl = pathToFileURL(path.resolve("dist/paths.js")).href;
+
+  mkdirSync(mcpDir, { recursive: true });
+  writeFileSync(path.join(contextDir, "config.yaml"), "source_paths:\n  - src\n");
+
+  const result = spawnSync(
+    process.execPath,
+    [
+      "--input-type=module",
+      "-e",
+      `import { REPO_ROOT, CONTEXT_DIR, CACHE_DIR } from ${JSON.stringify(pathsModuleUrl)}; console.log(JSON.stringify({ REPO_ROOT, CONTEXT_DIR, CACHE_DIR }));`
+    ],
+    {
+      cwd: mcpDir,
+      encoding: "utf8"
+    }
+  );
+
+  assert.equal(result.status, 0, result.stderr);
+
+  const parsed = JSON.parse(result.stdout.trim());
+  const resolvedProjectRoot = realpathSync(projectRoot);
+  assert.equal(parsed.REPO_ROOT, resolvedProjectRoot);
+  assert.equal(parsed.CONTEXT_DIR, path.join(resolvedProjectRoot, ".context"));
+  assert.equal(parsed.CACHE_DIR, path.join(resolvedProjectRoot, ".context", "cache"));
+});

package/scaffold/mcp/tests/workflow-synced-capabilities.test.mjs

@@ -0,0 +1,226 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  loadSyncedCapabilities,
+  syncedCapabilitiesCachePath,
+} from "../dist/core/workflow/synced-capability-registry.js";
+import { evaluateToolCall } from "../dist/core/workflow/enforcement.js";
+import { createRun } from "../dist/core/workflow/run-lifecycle.js";
+
+function makeWorkspace() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "cortex-synced-caps-"));
+}
+
+const FRONTEND_BUILDER = {
+  name: "frontend-builder",
+  description: "Frontend-only profile",
+  read_globs: ["**"],
+  write_globs: ["src/components/**"],
+  tools_allowed: [],
+};
+
+const WORKFLOW = {
+  id: "fe",
+  description: "Frontend-only build",
+  version: 1,
+  stages: [
+    {
+      name: "build",
+      artifact: "changes.md",
+      reads: [],
+      required_fields: [],
+      validators: [],
+      capability: "frontend-builder",
+      description: "Build the frontend",
+    },
+  ],
+};
+
+function writeCache(dir, payload) {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    syncedCapabilitiesCachePath(dir),
+    JSON.stringify(payload, null, 2),
+    "utf8",
+  );
+}
+
+test("syncedCapabilitiesCachePath: defaults to ~/.cortex/capabilities.local.json", () => {
+  const expected = path.join(os.homedir(), ".cortex", "capabilities.local.json");
+  assert.equal(syncedCapabilitiesCachePath(), expected);
+});
+
+test("loadSyncedCapabilities: returns {} when cache is missing", () => {
+  const dir = makeWorkspace();
+  assert.deepEqual(loadSyncedCapabilities(dir), {});
+});
+
+test("loadSyncedCapabilities: returns {} when cache is unreadable JSON", () => {
+  const dir = makeWorkspace();
+  fs.writeFileSync(syncedCapabilitiesCachePath(dir), "not json", "utf8");
+  assert.deepEqual(loadSyncedCapabilities(dir), {});
+});
+
+test("loadSyncedCapabilities: returns {} when 'capabilities' key is missing", () => {
+  const dir = makeWorkspace();
+  writeCache(dir, { last_synced_at: "x" });
+  assert.deepEqual(loadSyncedCapabilities(dir), {});
+});
+
+test("loadSyncedCapabilities: drops entries whose definition fails schema", () => {
+  const dir = makeWorkspace();
+  writeCache(dir, {
+    capabilities: {
+      "valid-one": {
+        capability_name: "valid-one",
+        updated_at: "2026-05-07T12:00:00.000Z",
+        definition: FRONTEND_BUILDER,
+      },
+      "broken-one": {
+        capability_name: "broken-one",
+        updated_at: "2026-05-07T12:00:00.000Z",
+        definition: { name: "broken-one" /* missing description */ },
+      },
+    },
+  });
+  const loaded = loadSyncedCapabilities(dir);
+  assert.deepEqual(Object.keys(loaded).sort(), ["valid-one"]);
+});
+
+test("loadSyncedCapabilities: returns valid capability definitions", () => {
+  const dir = makeWorkspace();
+  writeCache(dir, {
+    capabilities: {
+      "frontend-builder": {
+        capability_name: "frontend-builder",
+        updated_at: "2026-05-07T12:00:00.000Z",
+        definition: FRONTEND_BUILDER,
+      },
+    },
+  });
+  const loaded = loadSyncedCapabilities(dir);
+  assert.equal(loaded["frontend-builder"].name, "frontend-builder");
+  assert.deepEqual(loaded["frontend-builder"].write_globs, ["src/components/**"]);
+});
+
+test("evaluateToolCall integration: synced capability is consulted via merged registry", () => {
+  const cwd = makeWorkspace();
+  // Sandbox the home-dir-based loader.
+  const fakeHome = makeWorkspace();
+  process.env.HOME = fakeHome;
+  try {
+    fs.mkdirSync(path.join(fakeHome, ".cortex"), { recursive: true });
+    fs.writeFileSync(
+      path.join(fakeHome, ".cortex", "capabilities.local.json"),
+      JSON.stringify({
+        capabilities: {
+          "frontend-builder": {
+            capability_name: "frontend-builder",
+            updated_at: "2026-05-07T12:00:00.000Z",
+            definition: FRONTEND_BUILDER,
+          },
+        },
+      }),
+      "utf8",
+    );
+
+    createRun({
+      cwd,
+      taskId: "task-1",
+      workflow: WORKFLOW,
+      taskDescription: "Build frontend",
+    });
+
+    // Allowed: src/components/**
+    const allowed = evaluateToolCall({
+      cwd,
+      taskId: "task-1",
+      call: { toolName: "Edit", toolInput: { file_path: "src/components/Foo.tsx" } },
+      workflows: { fe: WORKFLOW },
+    });
+    assert.equal(allowed.allowed, true);
+
+    // Blocked: outside write_globs
+    const blocked = evaluateToolCall({
+      cwd,
+      taskId: "task-1",
+      call: { toolName: "Edit", toolInput: { file_path: "src/server/api.ts" } },
+      workflows: { fe: WORKFLOW },
+    });
+    assert.equal(blocked.allowed, false);
+    assert.match(blocked.reason, /frontend-builder/);
+  } finally {
+    delete process.env.HOME;
+  }
+});
+
+test("evaluateToolCall integration: synced capability with same name as bundled overrides bundled", () => {
+  const cwd = makeWorkspace();
+  const fakeHome = makeWorkspace();
+  process.env.HOME = fakeHome;
+  try {
+    // Override the bundled "builder" capability with a much stricter version
+    // — only test files writable.
+    const stricterBuilder = {
+      name: "builder",
+      description: "Org-overridden strict builder",
+      read_globs: ["**"],
+      write_globs: ["tests/**"],
+      tools_allowed: [],
+    };
+    fs.mkdirSync(path.join(fakeHome, ".cortex"), { recursive: true });
+    fs.writeFileSync(
+      path.join(fakeHome, ".cortex", "capabilities.local.json"),
+      JSON.stringify({
+        capabilities: {
+          builder: {
+            capability_name: "builder",
+            updated_at: "2026-05-07T12:00:00.000Z",
+            definition: stricterBuilder,
+          },
+        },
+      }),
+      "utf8",
+    );
+
+    const builderWorkflow = {
+      id: "build-only",
+      description: "Build-only workflow using bundled name",
+      version: 1,
+      stages: [
+        {
+          name: "build",
+          artifact: "changes.md",
+          reads: [],
+          required_fields: [],
+          validators: [],
+          capability: "builder",
+          description: "Build",
+        },
+      ],
+    };
+    createRun({
+      cwd,
+      taskId: "task-2",
+      workflow: builderWorkflow,
+      taskDescription: "Build",
+    });
+
+    // Bundled builder allows src/** + tests/**, but the org override only
+    // allows tests/**. src/** must be blocked under the override.
+    const result = evaluateToolCall({
+      cwd,
+      taskId: "task-2",
+      call: { toolName: "Edit", toolInput: { file_path: "src/main.ts" } },
+      workflows: { "build-only": builderWorkflow },
+    });
+    assert.equal(result.allowed, false);
+    assert.match(result.reason, /Org-overridden|tests/i);
+  } finally {
+    delete process.env.HOME;
+  }
+});

package/scaffold/scripts/embed.sh

@@ -12,4 +12,4 @@ fi
 mkdir -p "$MCP_DIR/.npm-cache"
 
 echo "[embed] generating embeddings via .context/mcp/embed"
-NPM_CONFIG_CACHE="$MCP_DIR/.npm-cache" npm --prefix "$MCP_DIR" run embed --silent -- "$@"
+CORTEX_PROJECT_ROOT="$REPO_ROOT" NPM_CONFIG_CACHE="$MCP_DIR/.npm-cache" npm --prefix "$MCP_DIR" run embed --silent -- "$@"

package/scaffold/scripts/load-ryu.sh

@@ -15,4 +15,4 @@ if [[ ! -d "$MCP_DIR/node_modules" ]]; then
   exit 1
 fi
 
-NPM_CONFIG_CACHE="$MCP_DIR/.npm-cache" npm --prefix "$MCP_DIR" run graph:load -- "$@"
+CORTEX_PROJECT_ROOT="$REPO_ROOT" NPM_CONFIG_CACHE="$MCP_DIR/.npm-cache" npm --prefix "$MCP_DIR" run graph:load -- "$@"