@danielblomma/cortex-mcp 2.0.16 → 2.0.19

package/README.md

@@ -97,7 +97,7 @@ cortex init --bootstrap
 
 This will:
 
-- scaffold `.context/`, `scripts/`, `mcp/`, `.githooks/`, and docs files
+- scaffold `.context/`, `.context/scripts/`, `.context/mcp/`, `.githooks/`, and docs files
 - activate git hooks for checkout, pull/merge, commit, and rewrite events
 - build and prepare the local MCP server
 - try to auto-register MCP connections for Claude/Codex (if installed)
@@ -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/bin/cortex.mjs

@@ -27,11 +27,14 @@ const PACKAGE_JSON_PATH = path.join(PACKAGE_ROOT, "package.json");
 // only the three editable config files". Generated artifacts (db,
 // embeddings, cache, hooks, mcp/, govern.local.json) never land in git.
 const MCP_PROJECT_REL = path.join(".context", "mcp");
+const CONTEXT_SCRIPTS_REL = path.join(".context", "scripts");
 
+// `.context/*` (not `.context/`) so the !-negations below actually re-include
+// the config files — git can't re-include children of an excluded directory.
 const GITIGNORE_LINES = [
   "",
   "# Cortex local storage",
-  ".context/",
+  ".context/*",
   "!.context/config.yaml",
   "!.context/rules.yaml",
   "!.context/ontology.cypher",
@@ -461,12 +464,73 @@ function migrateLegacyMcpLocation(targetDir) {
   );
 }
 
+const LEGACY_SCRIPT_ENTRIES = [
+  "bootstrap.sh",
+  "context.sh",
+  "dashboard.mjs",
+  "dashboard.sh",
+  "doctor.sh",
+  "embed.sh",
+  "ingest.mjs",
+  "ingest.sh",
+  "install-git-hooks.sh",
+  "load-kuzu.sh",
+  "load-ryu.sh",
+  "memory-compile.mjs",
+  "memory-compile.sh",
+  "memory-lint.mjs",
+  "memory-lint.sh",
+  "refresh.sh",
+  "status.sh",
+  "update-context.sh",
+  "watch.sh",
+  "lib",
+  "parsers"
+];
+
+function looksLikeLegacyCortexScriptsDir(scriptsDir) {
+  const contextScript = path.join(scriptsDir, "context.sh");
+  if (!fs.existsSync(contextScript)) {
+    return false;
+  }
+  try {
+    const contents = fs.readFileSync(contextScript, "utf8");
+    return contents.includes("bootstrap)") && contents.includes("graph-load)") && contents.includes("memory-lint)");
+  } catch {
+    return false;
+  }
+}
+
+function removeLegacyCortexScripts(targetDir) {
+  if (path.resolve(targetDir) === PACKAGE_ROOT) {
+    return;
+  }
+
+  const scriptsDir = path.join(targetDir, "scripts");
+  if (!looksLikeLegacyCortexScriptsDir(scriptsDir)) {
+    return;
+  }
+
+  for (const entry of LEGACY_SCRIPT_ENTRIES) {
+    fs.rmSync(path.join(scriptsDir, entry), { recursive: true, force: true });
+  }
+
+  try {
+    if (fs.existsSync(scriptsDir) && fs.readdirSync(scriptsDir).length === 0) {
+      fs.rmdirSync(scriptsDir);
+    }
+  } catch {
+    // Best effort. A user's own files in scripts/ must remain untouched.
+  }
+}
+
 function installScaffold(targetDir, force) {
   migrateLegacyMcpLocation(targetDir);
+  removeLegacyCortexScripts(targetDir);
 
   const copyMap = [
     [path.join(SCAFFOLD_ROOT, ".context"), path.join(targetDir, ".context")],
-    [path.join(SCAFFOLD_ROOT, "scripts"), path.join(targetDir, "scripts")],
+    [path.join(SCAFFOLD_ROOT, "scripts"), path.join(targetDir, CONTEXT_SCRIPTS_REL)],
     [path.join(SCAFFOLD_ROOT, "mcp"), path.join(targetDir, MCP_PROJECT_REL)],
     [path.join(SCAFFOLD_ROOT, ".githooks"), path.join(targetDir, ".githooks")]
   ];
@@ -720,7 +784,7 @@ async function connectMcpClients(targetDir, options = {}) {
 }
 
 async function maybeInstallGitHooks(targetDir) {
-  const installScript = path.join(targetDir, "scripts", "install-git-hooks.sh");
+  const installScript = path.join(targetDir, CONTEXT_SCRIPTS_REL, "install-git-hooks.sh");
   if (!fs.existsSync(installScript)) {
     return false;
   }
@@ -758,16 +822,17 @@ function isTruthyEnv(value) {
 function canAutoInitialize(targetDir) {
   // Legacy mcp/ at root no longer counted — pre-v2.0.5 projects are migrated
   // by installScaffold rather than blocking auto-init.
-  const scaffoldPaths = [".context", "scripts", ".githooks"].map((entry) => path.join(targetDir, entry));
+  const scaffoldPaths = [".context", ".githooks"].map((entry) => path.join(targetDir, entry));
   return scaffoldPaths.every((entryPath) => !fs.existsSync(entryPath));
 }
 
 function isScaffoldOutOfDate(targetDir) {
-  const contextScript = path.join(targetDir, "scripts", "context.sh");
+  const contextScript = path.join(targetDir, CONTEXT_SCRIPTS_REL, "context.sh");
+  const legacyContextScript = path.join(targetDir, "scripts", "context.sh");
   if (!fs.existsSync(contextScript)) {
-    return false;
+    return fs.existsSync(legacyContextScript);
   }
-  const doctorScript = path.join(targetDir, "scripts", "doctor.sh");
+  const doctorScript = path.join(targetDir, CONTEXT_SCRIPTS_REL, "doctor.sh");
   if (!fs.existsSync(doctorScript)) {
     return true;
   }
@@ -812,7 +877,7 @@ async function maybeMigrateScaffold(targetDir, command) {
 
   console.error(
     `[cortex] scaffold in ${targetDir} is out of date ` +
-      `(missing scripts/doctor.sh, .context/mcp/package.json, doctor subcommand in context.sh, ` +
+      `(missing .context/scripts/doctor.sh, .context/mcp/package.json, doctor subcommand in context.sh, ` +
       `or carries a legacy mcp/ directory at the project root).`
   );
 
@@ -881,7 +946,7 @@ async function ensureProjectInitializedForMcp(targetDir) {
 }
 
 async function runContextCommand(cwd, contextArgs) {
-  const contextScript = path.join(cwd, "scripts", "context.sh");
+  const contextScript = path.join(cwd, CONTEXT_SCRIPTS_REL, "context.sh");
   if (!fs.existsSync(contextScript)) {
     throw new Error(`Missing ${contextScript}. Run 'cortex init' first.`);
   }
@@ -915,7 +980,7 @@ async function run() {
     await maybeInstallGitHooks(target);
 
     console.log(`[cortex] initialized in ${target}`);
-    console.log("[cortex] scaffold copied: .context/, scripts/, mcp/, .githooks/, docs/");
+    console.log("[cortex] scaffold copied: .context/, .context/scripts/, .context/mcp/, .githooks/, docs/");
     console.log(`[cortex] Claude commands ready: /context-update (${helpers.claude.total} files)`);
     if (helpers.codex.changed) {
       console.log("[cortex] Codex workflow instructions added to AGENTS.md");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.16",
+  "version": "2.0.19",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",
@@ -49,6 +49,7 @@
     "docs/MCP_MARKETPLACE.md"
   ],
   "scripts": {
+    "pretest": "test -d scaffold/scripts/parsers/node_modules || npm --prefix scaffold/scripts/parsers install --no-fund --no-update-notifier --silent",
     "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.test.mjs tests/javascript-parser.test.mjs tests/sql-parser.test.mjs tests/config-parser.test.mjs tests/resources-parser.test.mjs tests/vbnet-parser.test.mjs tests/cpp-parser.test.mjs tests/dashboard.test.mjs tests/init-config.test.mjs tests/init-agents.test.mjs tests/multi-level.test.mjs tests/no-legacy-paths.test.mjs tests/tree-sitter-error-reporting.test.mjs tests/tree-sitter-body-cap.test.mjs tests/tree-sitter-exported.test.mjs tests/tree-sitter-robustness.test.mjs",
     "release:sync-version": "node scripts/sync-release-version.mjs",
     "release:check-version-sync": "node scripts/sync-release-version.mjs --check",

package/scaffold/.context/config.yaml

@@ -1,11 +1,10 @@
 repo_id: cortex
 source_paths:
-  - src
+  - scripts
+  - mcp/src
   - docs
-  - design
   - .context/notes
   - .context/decisions
-  - README.md
 truth_order:
   - ADR
   - RULE

package/scaffold/.githooks/_cortex-update-runner.sh

@@ -6,12 +6,12 @@ if [[ -z "$REPO_ROOT" ]]; then
   exit 0
 fi
 
-CONTEXT_SCRIPT="$REPO_ROOT/scripts/context.sh"
+CONTEXT_SCRIPT="$REPO_ROOT/.context/scripts/context.sh"
 if [[ ! -x "$CONTEXT_SCRIPT" ]]; then
   exit 0
 fi
 
-PARSER_MODULES_DIR="$REPO_ROOT/scripts/parsers/node_modules"
+PARSER_MODULES_DIR="$REPO_ROOT/.context/scripts/parsers/node_modules"
 
 HOOK_DIR="$REPO_ROOT/.context/hooks"
 LOCK_DIR="$HOOK_DIR/update.lock"

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";