@danielblomma/cortex-mcp 2.0.15 → 2.0.18

package/README.md

@@ -346,11 +346,13 @@ This repository includes two GitHub Actions workflows:
   - Triggers on tag push `v*.*.*`
   - Verifies tag/version sync
   - Runs root tests + MCP build/tests
-  - Publishes `@danielblomma/cortex-mcp` to npm
+  - Publishes `@danielblomma/cortex-mcp` to npm via npm trusted publishing (GitHub OIDC)
 
-Required GitHub secret:
+Required npm configuration:
 
-- `NPM_TOKEN` (npm automation token with publish rights for `@danielblomma/cortex-mcp`)
+- Configure a trusted publisher for `@danielblomma/cortex-mcp` on npmjs.com
+- Use GitHub Actions publisher `DanielBlomma/cortex`
+- Workflow filename must match `release-publish.yml`
 
 ## Limitations
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.15",
+  "version": "2.0.18",
   "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-lock.json

@@ -91,12 +91,6 @@
       "integrity": "sha512-MI1qs7Lo4Syw0EOzUl0xjs2lsoeqFku44KpngfIduHBYvzm8h2+7K8YMQh1JtVVVrUvhLpNwqVi4DERegUJhPQ==",
       "license": "Apache-2.0"
     },
-    "node_modules/@huggingface/transformers/node_modules/long": {
-      "version": "5.3.2",
-      "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
-      "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
-      "license": "Apache-2.0"
-    },
     "node_modules/@huggingface/transformers/node_modules/onnxruntime-common": {
       "version": "1.24.3",
       "resolved": "https://registry.npmjs.org/onnxruntime-common/-/onnxruntime-common-1.24.3.tgz",
@@ -140,30 +134,6 @@
       "integrity": "sha512-BOoomdHYmNRL5r4iQ4bMvsl2t0/hzVQ3OM3PHD0gxeXu1PmggqBv3puZicEUVOA3AtHHYmqZtjMj9FOfGrATTw==",
       "license": "MIT"
     },
-    "node_modules/@huggingface/transformers/node_modules/protobufjs": {
-      "version": "7.5.5",
-      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.5.tgz",
-      "integrity": "sha512-3wY1AxV+VBNW8Yypfd1yQY9pXnqTAN+KwQxL8iYm3/BjKYMNg4i0owhEe26PWDOMaIrzeeF98Lqd5NGz4omiIg==",
-      "hasInstallScript": true,
-      "license": "BSD-3-Clause",
-      "dependencies": {
-        "@protobufjs/aspromise": "^1.1.2",
-        "@protobufjs/base64": "^1.1.2",
-        "@protobufjs/codegen": "^2.0.4",
-        "@protobufjs/eventemitter": "^1.1.0",
-        "@protobufjs/fetch": "^1.1.0",
-        "@protobufjs/float": "^1.0.2",
-        "@protobufjs/inquire": "^1.1.0",
-        "@protobufjs/path": "^1.1.2",
-        "@protobufjs/pool": "^1.1.0",
-        "@protobufjs/utf8": "^1.1.0",
-        "@types/node": ">=13.7.0",
-        "long": "^5.0.0"
-      },
-      "engines": {
-        "node": ">=12.0.0"
-      }
-    },
     "node_modules/@huggingface/transformers/node_modules/sharp": {
       "version": "0.34.5",
       "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz",
@@ -766,9 +736,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/codegen": {
-      "version": "2.0.4",
-      "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.4.tgz",
-      "integrity": "sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==",
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz",
+      "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==",
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/eventemitter": {
@@ -778,13 +748,12 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/fetch": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.0.tgz",
-      "integrity": "sha512-lljVXpqXebpsijW71PZaCYeIcE5on1w5DlQy5WH6GLbFryLUrBD4932W/E2BSpfRJWseIL4v/KPgBFxDOIdKpQ==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz",
+      "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==",
       "license": "BSD-3-Clause",
       "dependencies": {
-        "@protobufjs/aspromise": "^1.1.1",
-        "@protobufjs/inquire": "^1.1.0"
+        "@protobufjs/aspromise": "^1.1.1"
       }
     },
     "node_modules/@protobufjs/float": {
@@ -794,9 +763,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/inquire": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.0.tgz",
-      "integrity": "sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==",
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.2.tgz",
+      "integrity": "sha512-pa0vFRuws4wkvaXKK1uXZMAwAX4/t8ANaJo45iw/oQHNQ9q5xUzwgFmVJGXiga2BeN+zpX7Vf9vmsiIa2J+MUw==",
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/path": {
@@ -812,9 +781,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/utf8": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.0.tgz",
-      "integrity": "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.1.tgz",
+      "integrity": "sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==",
       "license": "BSD-3-Clause"
     },
     "node_modules/@tsconfig/node10": {
@@ -1044,9 +1013,9 @@
       "license": "MIT"
     },
     "node_modules/brace-expansion": {
-      "version": "5.0.5",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
-      "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==",
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz",
+      "integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^4.0.2"
@@ -1525,12 +1494,12 @@
       }
     },
     "node_modules/express-rate-limit": {
-      "version": "8.3.1",
-      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.3.1.tgz",
-      "integrity": "sha512-D1dKN+cmyPWuvB+G2SREQDzPY1agpBIcTa9sJxOPMCNeH3gwzhqJRDWCXW3gg0y//+LQ/8j52JbMROWyrKdMdw==",
+      "version": "8.5.1",
+      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.5.1.tgz",
+      "integrity": "sha512-5O6KYmyJEpuPJV5hNTXKbAHWRqrzyu+OI3vUnSd2kXFubIVpG7ezpgxQy76Zo5GQZtrQBg86hF+CM/NX+cioiQ==",
       "license": "MIT",
       "dependencies": {
-        "ip-address": "10.1.0"
+        "ip-address": "^10.2.0"
       },
       "engines": {
         "node": ">= 16"
@@ -1574,9 +1543,9 @@
       "license": "MIT"
     },
     "node_modules/fast-uri": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
-      "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz",
+      "integrity": "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==",
       "funding": [
         {
           "type": "github",
@@ -1791,9 +1760,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.14",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.14.tgz",
-      "integrity": "sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w==",
+      "version": "4.12.18",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.18.tgz",
+      "integrity": "sha512-RWzP96k/yv0PQfyXnWjs6zot20TqfpfsNXhOnev8d1InAxubW93L11/oNUc3tQqn2G0bSdAOBpX+2uDFHV7kdQ==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
@@ -1848,9 +1817,9 @@
       "license": "ISC"
     },
     "node_modules/ip-address": {
-      "version": "10.1.0",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
-      "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
+      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"
@@ -1937,6 +1906,12 @@
         "graceful-fs": "^4.1.6"
       }
     },
+    "node_modules/long": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
+      "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
+      "license": "Apache-2.0"
+    },
     "node_modules/make-error": {
       "version": "1.3.6",
       "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
@@ -2152,6 +2127,30 @@
       "integrity": "sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==",
       "license": "MIT"
     },
+    "node_modules/protobufjs": {
+      "version": "7.5.9",
+      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.9.tgz",
+      "integrity": "sha512-Od4muIm3HW1AouyHF5lONOf1FWo3hY1NbFDoy191X9GzhpgW1clCoaFjfVs2rKJNFYpTNJbje4cbAIDBZJ63ZA==",
+      "hasInstallScript": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@protobufjs/aspromise": "^1.1.2",
+        "@protobufjs/base64": "^1.1.2",
+        "@protobufjs/codegen": "^2.0.5",
+        "@protobufjs/eventemitter": "^1.1.0",
+        "@protobufjs/fetch": "^1.1.1",
+        "@protobufjs/float": "^1.0.2",
+        "@protobufjs/inquire": "^1.1.2",
+        "@protobufjs/path": "^1.1.2",
+        "@protobufjs/pool": "^1.1.0",
+        "@protobufjs/utf8": "^1.1.1",
+        "@types/node": ">=13.7.0",
+        "long": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",

package/scaffold/mcp/package.json

@@ -23,8 +23,8 @@
   },
   "overrides": {
     "cmake-js": "^8.0.0",
-    "express-rate-limit": "^8.3.1",
-    "hono": "^4.12.14",
+    "express-rate-limit": "^8.5.1",
+    "hono": "^4.12.18",
     "@hono/node-server": "^1.19.13",
     "tar": "^7.5.11"
   },

package/scaffold/mcp/src/cli/stage.ts

@@ -8,8 +8,8 @@ import {
   type StageStatus,
   type WorkflowDefinition,
 } from "../core/workflow/index.js";
-import { DEFAULT_WORKFLOWS } from "../core/workflow/default-workflows.js";
-import { isEnterpriseProject } from "../hooks/shared.js";
+import { resolveWorkflowDefinition } from "../core/workflow/resolution.js";
+import { isEnforcedMode, isEnterpriseProject } from "../hooks/shared.js";
 
 /**
  * `cortex stage` CLI surface. Each subcommand is a thin shell wrapper
@@ -93,18 +93,6 @@ function projectRoot(): string {
   return process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
 }
 
-function resolveWorkflow(workflowId: string): WorkflowDefinition {
-  const wf = DEFAULT_WORKFLOWS[workflowId];
-  if (!wf) {
-    throw new Error(
-      `Unknown workflow_id: ${workflowId}. Available: ${
-        Object.keys(DEFAULT_WORKFLOWS).join(", ") || "<none>"
-      }`,
-    );
-  }
-  return wf;
-}
-
 type Flags = Record<string, string | boolean>;
 
 function parseFlags(args: string[]): { flags: Flags; rest: string[] } {
@@ -153,7 +141,11 @@ async function runStart(args: string[]): Promise<void> {
   const workflowId =
     typeof flags.workflow === "string" ? flags.workflow : "secure-build";
 
-  const workflow = resolveWorkflow(workflowId);
+  const resolved = resolveWorkflowDefinition(workflowId, {
+    emitBundledFallbackWarning: true,
+    bundledFallbackPolicy: isEnforcedMode(projectRoot()) ? "block" : "warn",
+  });
+  const workflow = resolved.workflow;
   const state = createRun({
     cwd: projectRoot(),
     taskId,
@@ -165,7 +157,12 @@ async function runStart(args: string[]): Promise<void> {
     taskId,
     workflow,
   });
-  emitJson({ state, envelope });
+  emitJson({
+    state,
+    envelope,
+    workflow_source: resolved.source,
+    warnings: resolved.warnings,
+  });
 }
 
 async function runStatus(args: string[]): Promise<void> {
@@ -186,7 +183,7 @@ async function runEnvelope(args: string[]): Promise<void> {
       `No run state for task ${taskId}. Start one with 'cortex stage start'.`,
     );
   }
-  const workflow = resolveWorkflow(state.workflow_id);
+  const workflow = resolveWorkflowDefinition(state.workflow_id).workflow;
   const envelope = composeStageEnvelope({
     cwd: projectRoot(),
     taskId,
@@ -246,7 +243,7 @@ async function runAdvance(args: string[]): Promise<void> {
       `No run state for task ${taskId}. Start one with 'cortex stage start'.`,
     );
   }
-  const workflow = resolveWorkflow(state.workflow_id);
+  const workflow = resolveWorkflowDefinition(state.workflow_id).workflow;
   const stage = workflow.stages.find((s) => s.name === stageName);
   if (!stage) {
     throw new Error(

package/scaffold/mcp/src/cli/telemetry-test.ts

@@ -6,6 +6,7 @@ import {
   loadEnterpriseConfig,
   resolveEnterpriseActivation,
 } from "../core/config.js";
+import { telemetryStatePath } from "../core/telemetry/state-dir.js";
 import { pushMetrics } from "../enterprise/telemetry/sync.js";
 import type { TelemetryMetrics } from "../core/telemetry/collector.js";
 
@@ -25,7 +26,7 @@ import type { TelemetryMetrics } from "../core/telemetry/collector.js";
  */
 
 function readMachineId(contextDir: string): string {
-  const path = join(contextDir, "telemetry", "machine_id");
+  const path = telemetryStatePath(contextDir, "machine_id");
   if (existsSync(path)) {
     try {
       const id = readFileSync(path, "utf8").trim();

package/scaffold/mcp/src/core/license.ts

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
+import { resolveTelemetryStateDir, telemetryStatePath } from "./telemetry/state-dir.js";
 
 export type LicenseVerification =
   | {
@@ -30,7 +31,7 @@ const GRACE_PERIOD_MS = 7 * 24 * 60 * 60 * 1000; // 7d grace if endpoint unreach
 const REQUEST_TIMEOUT_MS = 5000;
 
 function cachePath(contextDir: string): string {
-  return join(contextDir, "telemetry", CACHE_FILE);
+  return telemetryStatePath(contextDir, CACHE_FILE);
 }
 
 function readCache(contextDir: string): CacheEntry | null {
@@ -47,7 +48,7 @@ function readCache(contextDir: string): CacheEntry | null {
 function writeCache(contextDir: string, entry: CacheEntry): void {
   const path = cachePath(contextDir);
   try {
-    mkdirSync(join(contextDir, "telemetry"), { recursive: true });
+    mkdirSync(resolveTelemetryStateDir(contextDir), { recursive: true });
     writeFileSync(path, JSON.stringify(entry, null, 2), "utf8");
   } catch {
     // Cache failures are non-fatal — license check just won't be cached.

package/scaffold/mcp/src/core/telemetry/collector.ts

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { hostname, platform, arch } from "node:os";
 import { join } from "node:path";
+import { resolveTelemetryStateDir, telemetryStatePath } from "./state-dir.js";
 
 export type TelemetryMetrics = {
   period_start: string;
@@ -37,7 +38,8 @@ export type TelemetryMetrics = {
 const AVG_TOKENS_PER_RESULT = 400;
 
 function generateInstanceId(contextDir: string): string {
-  const idPath = join(contextDir, "telemetry", "machine_id");
+  const telemetryDir = resolveTelemetryStateDir(contextDir);
+  const idPath = join(telemetryDir, "machine_id");
   if (existsSync(idPath)) {
     try {
       const existing = readFileSync(idPath, "utf8").trim();
@@ -51,7 +53,7 @@ function generateInstanceId(contextDir: string): string {
   const fingerprint = `${hostname()}|${platform()}|${arch()}`;
   const id = createHash("sha256").update(fingerprint).digest("hex").slice(0, 16);
   try {
-    mkdirSync(join(contextDir, "telemetry"), { recursive: true });
+    mkdirSync(telemetryDir, { recursive: true });
     writeFileSync(idPath, id, "utf8");
   } catch (err) {
     process.stderr.write(`[cortex-enterprise] Could not persist instance id: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -142,8 +144,7 @@ export class TelemetryCollector {
   constructor(contextDir: string, clientVersion = "unknown") {
     this.clientVersion = clientVersion;
     this.instanceId = generateInstanceId(contextDir);
-    const telemetryDir = join(contextDir, "telemetry");
-    this.metricsPath = join(telemetryDir, "metrics.json");
+    this.metricsPath = telemetryStatePath(contextDir, "metrics.json");
 
     // Load existing metrics or start fresh
     try {

package/scaffold/mcp/src/core/telemetry/state-dir.ts

@@ -0,0 +1,40 @@
+import { accessSync, constants, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const warnedFallbacks = new Set<string>();
+
+function canUseDirectory(dir: string): boolean {
+  try {
+    mkdirSync(dir, { recursive: true });
+    accessSync(dir, constants.R_OK | constants.W_OK | constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveTelemetryStateDir(contextDir: string): string {
+  const primary = join(contextDir, "telemetry");
+  if (canUseDirectory(primary)) return primary;
+
+  const fallback = join(contextDir, "cache", "telemetry");
+  if (canUseDirectory(fallback)) {
+    const warningKey = `${primary}->${fallback}`;
+    if (!warnedFallbacks.has(warningKey)) {
+      warnedFallbacks.add(warningKey);
+      process.stderr.write(
+        `[cortex-enterprise] telemetry dir not writable at ${primary}; using ${fallback}\n`,
+      );
+    }
+    return fallback;
+  }
+
+  return primary;
+}
+
+export function telemetryStatePath(
+  contextDir: string,
+  ...parts: string[]
+): string {
+  return join(resolveTelemetryStateDir(contextDir), ...parts);
+}

package/scaffold/mcp/src/core/validators/builtins.ts

@@ -100,6 +100,21 @@ type ReviewStatusPayload = {
   reviewedFiles: ReviewedFileSnapshot[] | null;
 };
 
+function formatReviewEvidenceSource(
+  source: ReviewStatusPayload["source"] | "none",
+): string {
+  switch (source) {
+    case "workflow-state":
+      return "workflow state";
+    case "workflow-artifact":
+      return "workflow artifact";
+    case "legacy-review-status":
+      return "legacy file";
+    default:
+      return "none";
+  }
+}
+
 type ReviewedFileSnapshot = {
   path: string;
   exists: boolean;
@@ -474,7 +489,9 @@ registerValidator({
         pass: false,
         severity: "warning",
         message: `${sourceLabel} at ${reviewStatus.timestamp} is stale for current changes`,
-        detail: `Source: ${reviewStatus.source}. ${freshness.detail ?? "Current changes no longer match the reviewed code."}`,
+        detail:
+          `Source: ${formatReviewEvidenceSource(reviewStatus.source)}. ` +
+          `${freshness.detail ?? "Current changes no longer match the reviewed code."}`,
       };
     }
 
@@ -485,7 +502,7 @@ registerValidator({
         message: reviewStatus.reviewed
           ? `Enterprise review completed by ${reviewStatus.reviewer} at ${reviewStatus.timestamp}`
           : `Enterprise review recorded at ${reviewStatus.timestamp} but did not pass`,
-        detail: `Source: ${reviewStatus.source}`,
+        detail: `Source: ${formatReviewEvidenceSource(reviewStatus.source)}`,
       };
     }
 
@@ -496,7 +513,9 @@ registerValidator({
         message: reviewStatus.reviewed
           ? `Code review completed by ${reviewStatus.reviewer} at ${reviewStatus.timestamp}`
           : "Code review recorded but not approved",
-        detail: reviewStatus.reviewed ? undefined : `Source: ${reviewStatus.source}`,
+        detail: reviewStatus.reviewed
+          ? undefined
+          : `Source: ${formatReviewEvidenceSource(reviewStatus.source)}`,
       };
     }
 
@@ -504,7 +523,8 @@ registerValidator({
       pass: false,
       severity: "warning",
       message: "No code review recorded for current changes",
-      detail: "Run /review or context.review, or ensure your CI writes .context/review-status.json.",
+      detail:
+        "Source: none. Run /review or context.review, or ensure your CI writes .context/review-status.json.",
     };
   },
 });

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

@@ -8,3 +8,4 @@ export * from "./capabilities.js";
 export * from "./enforcement.js";
 export * from "./synced-registry.js";
 export * from "./synced-capability-registry.js";
+export * from "./resolution.js";

package/scaffold/mcp/src/core/workflow/mcp-tools.ts

@@ -1,8 +1,7 @@
 import { z } from "zod";
 import { advanceStage, createRun, getRunState } from "./run-lifecycle.js";
 import { composeStageEnvelope } from "./envelope.js";
-import { DEFAULT_WORKFLOWS } from "./default-workflows.js";
-import { loadSyncedWorkflows } from "./synced-registry.js";
+import { resolveWorkflowDefinition } from "./resolution.js";
 import {
   stageOverrideSchema,
   stageStatusSchema,
@@ -88,33 +87,18 @@ export function resolveProjectRoot(): string {
 export type WorkflowToolContext = {
   cwd: string;
   workflows?: Record<string, WorkflowDefinition>;
+  bundledFallbackPolicy?: "allow" | "warn" | "block";
 };
 
-function resolveWorkflow(
-  workflowId: string,
-  registry: Record<string, WorkflowDefinition> | undefined,
-): WorkflowDefinition {
-  // When the caller passes an explicit registry, it wins outright (used
-  // by tests). Otherwise we merge bundled defaults with the org-authored
-  // workflows the daemon has synced into ~/.cortex/workflows.local.json,
-  // with the synced ones taking precedence on workflow_id collisions so
-  // org overrides actually override.
-  const workflows =
-    registry ?? { ...DEFAULT_WORKFLOWS, ...loadSyncedWorkflows() };
-  const workflow = workflows[workflowId];
-  if (!workflow) {
-    throw new Error(
-      `Unknown workflow_id: ${workflowId}. Available: ${Object.keys(workflows).join(", ") || "<none>"}`,
-    );
-  }
-  return workflow;
-}
-
 export function runWorkflowStart(
   input: WorkflowStartInputT,
   ctx: WorkflowToolContext,
 ) {
-  const workflow = resolveWorkflow(input.workflow_id, ctx.workflows);
+  const resolved = resolveWorkflowDefinition(input.workflow_id, {
+    registry: ctx.workflows,
+    bundledFallbackPolicy: ctx.bundledFallbackPolicy,
+  });
+  const workflow = resolved.workflow;
   const state = createRun({
     cwd: ctx.cwd,
     taskId: input.task_id,
@@ -129,6 +113,8 @@ export function runWorkflowStart(
   return {
     state,
     envelope,
+    workflow_source: resolved.source,
+    warnings: resolved.warnings,
   };
 }
 
@@ -142,7 +128,9 @@ export function runWorkflowAdvance(
       `No run state found for task ${input.task_id}. Call cortex.workflow.start first.`,
     );
   }
-  const workflow = resolveWorkflow(state.workflow_id, ctx.workflows);
+  const workflow = resolveWorkflowDefinition(state.workflow_id, {
+    registry: ctx.workflows,
+  }).workflow;
   const stage = workflow.stages.find((s) => s.name === input.stage);
   if (!stage) {
     throw new Error(`Stage ${input.stage} is not defined in workflow ${workflow.id}`);
@@ -220,7 +208,9 @@ export function runWorkflowEnvelope(
       `No run state found for task ${input.task_id}. Call cortex.workflow.start first.`,
     );
   }
-  const workflow = resolveWorkflow(state.workflow_id, ctx.workflows);
+  const workflow = resolveWorkflowDefinition(state.workflow_id, {
+    registry: ctx.workflows,
+  }).workflow;
   const envelope = composeStageEnvelope({
     cwd: ctx.cwd,
     taskId: input.task_id,