@danielblomma/cortex-mcp 2.0.16 → 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.16",
+  "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/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,

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

@@ -0,0 +1,113 @@
+import { DEFAULT_WORKFLOWS } from "./default-workflows.js";
+import { loadSyncedWorkflows } from "./synced-registry.js";
+import type { WorkflowDefinition } from "./schemas.js";
+
+export type WorkflowSource = "bundled" | "synced" | "injected";
+
+export type WorkflowResolutionWarning = {
+  code: "bundled-workflow-fallback";
+  workflow_id: string;
+  message: string;
+  bundled_available: boolean;
+  synced_available: boolean;
+};
+
+export type WorkflowResolution = {
+  workflow: WorkflowDefinition;
+  source: WorkflowSource;
+  warnings: WorkflowResolutionWarning[];
+  bundled_ids: string[];
+  synced_ids: string[];
+  available_ids: string[];
+};
+
+type ResolveWorkflowOptions = {
+  registry?: Record<string, WorkflowDefinition>;
+  syncedDir?: string;
+  emitBundledFallbackWarning?: boolean;
+  bundledFallbackPolicy?: "allow" | "warn" | "block";
+};
+
+function sortIds(ids: Iterable<string>): string[] {
+  return [...ids].sort((left, right) => left.localeCompare(right));
+}
+
+function formatIds(ids: string[]): string {
+  return ids.length > 0 ? ids.join(", ") : "<none>";
+}
+
+export function resolveWorkflowDefinition(
+  workflowId: string,
+  options: ResolveWorkflowOptions = {},
+): WorkflowResolution {
+  if (options.registry) {
+    const availableIds = sortIds(Object.keys(options.registry));
+    const workflow = options.registry[workflowId];
+    if (!workflow) {
+      throw new Error(
+        `Unknown workflow_id: ${workflowId}. Available injected: ${formatIds(availableIds)}`,
+      );
+    }
+    return {
+      workflow,
+      source: "injected",
+      warnings: [],
+      bundled_ids: [],
+      synced_ids: [],
+      available_ids: availableIds,
+    };
+  }
+
+  const bundled = DEFAULT_WORKFLOWS;
+  const synced = loadSyncedWorkflows(options.syncedDir);
+  const bundledIds = sortIds(Object.keys(bundled));
+  const syncedIds = sortIds(Object.keys(synced));
+  const merged = { ...bundled, ...synced };
+  const availableIds = sortIds(Object.keys(merged));
+  const workflow = merged[workflowId];
+
+  if (!workflow) {
+    throw new Error(
+      `Unknown workflow_id: ${workflowId}. Available bundled: ${formatIds(bundledIds)}. ` +
+        `Available synced: ${formatIds(syncedIds)}. Available all: ${formatIds(availableIds)}`,
+    );
+  }
+
+  const source: WorkflowSource = Object.prototype.hasOwnProperty.call(synced, workflowId)
+    ? "synced"
+    : "bundled";
+  const warnings: WorkflowResolutionWarning[] = [];
+  const fallbackPolicy = options.bundledFallbackPolicy ?? "allow";
+
+  if (source === "bundled" && fallbackPolicy === "block") {
+    throw new Error(
+      `Workflow "${workflowId}" is only available from the bundled registry, ` +
+        "but enforced govern mode requires a synced org workflow. " +
+        `Available synced: ${formatIds(syncedIds)}.`,
+    );
+  }
+
+  if (
+    source === "bundled" &&
+    (options.emitBundledFallbackWarning || fallbackPolicy === "warn")
+  ) {
+    warnings.push({
+      code: "bundled-workflow-fallback",
+      workflow_id: workflowId,
+      bundled_available: true,
+      synced_available: syncedIds.length > 0,
+      message:
+        `Workflow "${workflowId}" was resolved from the bundled registry because ` +
+        "no synced org workflow with that id exists in the local cache.",
+    });
+  }
+
+  return {
+    workflow,
+    source,
+    warnings,
+    bundled_ids: bundledIds,
+    synced_ids: syncedIds,
+    available_ids: availableIds,
+  };
+}

package/scaffold/mcp/src/enterprise/index.ts

@@ -17,7 +17,8 @@ import { registerEnterpriseTools } from "./tools/enterprise.js";
 import { registerHarnessTools } from "./tools/harness.js";
 import { pushViolations, setViolationPushContext } from "./violations/push.js";
 import { pushReviewResults, setReviewPushContext } from "./reviews/push.js";
-import { setWorkflowPushContext } from "./workflow/push.js";
+import { pushWorkflowSnapshot, setWorkflowPushContext } from "./workflow/push.js";
+import { hasWorkflowState, loadWorkflowState } from "./workflow/state.js";
 
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json") as { version: string };
@@ -32,6 +33,7 @@ let activeAuditWriter: AuditWriter | null = null;
 let activeInstanceId: string | null = null;
 let activeSessionId: string | null = null;
 let activeRepo: string | null = null;
+let activeContextDir: string | null = null;
 
 async function flushComplianceQueues(
   config: EnterpriseConfig,
@@ -64,6 +66,15 @@ async function flushComplianceQueues(
     if (!result.success) {
       process.stderr.write(`[cortex-enterprise] ${reason} reviews push failed: ${result.error}\n`);
     }
+    if (result.attempted && activeContextDir && hasWorkflowState(activeContextDir)) {
+      const workflowState = loadWorkflowState(activeContextDir);
+      const workflowResult = await pushWorkflowSnapshot(baseUrl, apiKey, workflowState);
+      if (!workflowResult.success) {
+        process.stderr.write(
+          `[cortex-enterprise] ${reason} workflow snapshot refresh after review push failed: ${workflowResult.error}\n`,
+        );
+      }
+    }
   } catch (err) {
     process.stderr.write(`[cortex-enterprise] ${reason} reviews push error: ${err}\n`);
   }
@@ -113,6 +124,7 @@ export function shutdown(): void {
   activeInstanceId = null;
   activeSessionId = null;
   activeRepo = null;
+  activeContextDir = null;
   setAuditPushContext({});
   setViolationPushContext({});
   setReviewPushContext({});
@@ -248,6 +260,7 @@ export async function onSessionEvent(event: SessionEvent): Promise<void> {
 export async function register(server: McpServer): Promise<void> {
   const projectRoot = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
   const contextDir = path.join(projectRoot, ".context");
+  activeContextDir = contextDir;
 
   const config = loadEnterpriseConfig(contextDir);
   const activation = resolveEnterpriseActivation(config);
@@ -295,6 +308,8 @@ export async function register(server: McpServer): Promise<void> {
     repo: activeRepo ?? undefined,
     instance_id: activeInstanceId ?? undefined,
     session_id: activeSessionId ?? undefined,
+    context_dir: contextDir,
+    project_root: projectRoot,
   });
   setWorkflowPushContext({
     repo: activeRepo ?? undefined,