@danielblomma/cortex-mcp 2.2.4 → 2.4.0

package/README.md

@@ -143,6 +143,26 @@ Check context status:
 cortex status
 ```
 
+## Agent plugin (Claude Code + Codex)
+
+The `plugins/cortex` directory is a dual-manifest agent plugin: five behavior
+skills (`using-cortex`, `repo-research`, `change-impact`, `pattern-review`,
+`context-review`), a SessionStart bootstrap that re-injects Cortex
+instructions after new sessions, `/clear`, and compaction (Claude Code), and
+an MCP config that follows the active workspace.
+
+Claude Code:
+
+```bash
+/plugin marketplace add DanielBlomma/cortex
+/plugin install cortex@cortex
+```
+
+Codex discovers the same skills through `.codex-plugin/plugin.json`; repos
+initialized with `cortex init` also get an AGENTS.md bootstrap section as a
+fallback when the plugin is not installed. The CLI remains the engine — the
+plugin only adds the behavior layer, and `cortex connect` stays opt-in.
+
 ## Query From The CLI
 
 Use the CLI as the default local agent interface:
@@ -153,6 +173,7 @@ cortex related file:src/auth.ts --json
 cortex impact "payment service" --json
 cortex rules --json
 cortex explain "where retries are configured" --json
+cortex pattern-evidence src/auth.ts --query "error handling" --json
 ```
 
 These commands read the same local graph, embeddings, and rules used by the MCP server, but they do not require an MCP client registration.
@@ -381,12 +402,39 @@ cortex related <entity-id> [--json]
 cortex impact <query|entity-id> [--json]
 cortex rules [--json]
 cortex explain <query|entity-id> [--json]
+cortex pattern-evidence <file-path|entity-id> [--query <text>] [--top-k <n>] [--json]
 cortex status
 cortex dashboard [--interval <sec>]
 cortex watch [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]
 cortex help
 ```
 
+## Enterprise Pattern Review
+
+Enterprise `context.review` includes bounded repo-local pattern context by
+default. This evidence is advisory and does not change policy validator totals,
+workflow approval, or review trust.
+
+Optional MCP inputs:
+
+- `include_pattern_evidence` — enable or disable pattern context (default `true`).
+- `pattern_query` — shared pattern query; otherwise Cortex derives one per file.
+- `pattern_top_k` — evidence items per locality tier, from 1 to 5 (default `2`).
+- `pattern_limit` — analyzed review targets, from 1 to 25 (default `10`).
+
+The response adds `pattern_review` with deterministic targets, the canonical
+review question, cited evidence tiers, explicit repository fallback, unindexed
+status, and omitted-file counts. Pattern evidence never constitutes automatic
+code approval. Enterprise pattern review is lexical-only and never downloads an
+embedding model or calls an external service.
+
+Every target uses the same response fields. `status` is one of
+`local_evidence`, `repo_fallback`, `no_evidence`, `not_indexed`, or `error`;
+`local_pattern_found` and `fallback_used` are always explicit booleans, and
+`evidence_order` plus all four `tiers` are always present. Unavailable evidence
+uses empty tiers and sanitized messages rather than local paths or runtime
+errors.
+
 ## Automated Release
 
 This repository includes two GitHub Actions workflows:
@@ -418,14 +466,21 @@ all derived from the available CPU cores, RAM, and repository size at run time
 (container memory limits included). No configuration is needed — on a laptop or
 a CI runner, cortex picks safe settings by itself.
 
-The embedding token budget defaults to `auto`, which preserves the embedding
-model's own maximum context. Cortex does not lower the default token budget
-just because a repository is large; lower caps can discard semantically useful
-text and are reserved for explicit benchmark or quality experiments. To force a
+The embedding token budget defaults to `auto`, which is quality-first but
+memory-aware. Cortex starts from the embedding model's own maximum context and
+only lowers the cap when the local memory headroom is unlikely to fit that
+model/context combination. Degraded auto runs are explicit in logs, for example
+`token_budget=auto_degraded reason=memory_headroom cap=2048`. To force a
 specific capped run, set `CORTEX_EMBED_MAX_TOKENS` to a number such as `2048`;
-set it to `model` or `full` to make the full-model baseline explicit. When
-several cortex instances share one machine, set `CORTEX_EMBED_THREADS` to give
-each its fair share of cores.
+set it to `model` or `full` to force the full-model baseline even on tight
+machines. When several cortex instances share one machine, set
+`CORTEX_EMBED_THREADS` to give each its fair share of cores.
+
+For experiments on very large repositories, `CORTEX_EMBED_TEXT_PROFILE=compact-files`
+compacts only large file-level embedding records while keeping chunk-level
+embedding text full. The default remains `full`; use the compact profile only
+with a before/after semantic quality check because file-level compaction can
+change retrieval behavior.
 
 ## Limitations
 

package/bin/cortex.mjs

@@ -81,6 +81,7 @@ function printHelp() {
   console.log(helpRow("impact <query|entity-id> [--json]", "Trace likely impact paths"));
   console.log(helpRow("rules [--json]", "List active context rules"));
   console.log(helpRow("explain <query|entity-id> [--json]", "Show search score evidence"));
+  console.log(helpRow("pattern-evidence <file|entity-id> [--query <text>] [--top-k <n>] [--json]", "Collect cited repo-local pattern evidence"));
   console.log(helpRow("dashboard [--interval <sec>]", "Live local dashboard"));
   console.log(helpRow("memory-compile [--dry-run] [--verbose]", "Compile memory artifacts"));
   console.log(helpRow("memory-lint [--verbose] [--json]", "Lint compiled memory"));
@@ -198,81 +199,7 @@ function ensureScaffoldExists() {
 // Files that should never be overwritten if they already exist in the target.
 // These contain user-specific configuration that would be lost on re-init.
 const PRESERVE_FILES = new Set(["config.yaml", "rules.yaml", "enterprise.yml", "enterprise.yaml", "CLAUDE.md", "AGENTS.md"]);
-const DEFAULT_SOURCE_PATHS = [
-  "src",
-  "docs",
-  "design",
-  ".context/notes",
-  ".context/decisions",
-  "README.md"
-];
-const INIT_SKIP_DIRECTORIES = new Set([
-  ".git",
-  ".idea",
-  ".vscode",
-  "node_modules",
-  "dist",
-  "build",
-  "coverage",
-  ".next",
-  ".cache",
-  ".context",
-  "scripts",
-  ".githooks",
-  "bin",
-  "obj"
-]);
-const INIT_SOURCE_EXTENSIONS = new Set([
-  ".md",
-  ".mdx",
-  ".txt",
-  ".adoc",
-  ".rst",
-  ".yaml",
-  ".yml",
-  ".json",
-  ".toml",
-  ".csv",
-  ".ts",
-  ".tsx",
-  ".mts",
-  ".cts",
-  ".js",
-  ".jsx",
-  ".mjs",
-  ".cjs",
-  ".py",
-  ".go",
-  ".java",
-  ".cs",
-  ".vb",
-  ".sln",
-  ".vbproj",
-  ".csproj",
-  ".fsproj",
-  ".props",
-  ".targets",
-  ".config",
-  ".resx",
-  ".settings",
-  ".rb",
-  ".rs",
-  ".php",
-  ".swift",
-  ".kt",
-  ".sql",
-  ".sh",
-  ".bash",
-  ".zsh",
-  ".ps1",
-  ".c",
-  ".h",
-  ".cpp",
-  ".hpp",
-  ".cc",
-  ".hh"
-]);
-const ROOT_DOC_PATHS = new Set(["docs", "design"]);
+const DEFAULT_SOURCE_PATHS = ["."];
 
 function copyDirectory(sourceDir, targetDir) {
   fs.mkdirSync(targetDir, { recursive: true });
@@ -318,92 +245,8 @@ function slugifyRepoId(value) {
   return dashed || "cortex";
 }
 
-function isInterestingSourceFile(fileName) {
-  const base = fileName.toLowerCase();
-  const ext = path.extname(fileName).toLowerCase();
-  return INIT_SOURCE_EXTENSIONS.has(ext) || base === "readme" || base.startsWith("readme.");
-}
-
-function directoryContainsInterestingFiles(directoryPath) {
-  const stack = [directoryPath];
-  while (stack.length > 0) {
-    const current = stack.pop();
-    let entries = [];
-    try {
-      entries = fs.readdirSync(current, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      const absolutePath = path.join(current, entry.name);
-      if (entry.isDirectory()) {
-        if (INIT_SKIP_DIRECTORIES.has(entry.name)) {
-          continue;
-        }
-        stack.push(absolutePath);
-        continue;
-      }
-
-      if (entry.isFile() && isInterestingSourceFile(entry.name)) {
-        return true;
-      }
-    }
-  }
-
-  return false;
-}
-
 function detectInitialSourcePaths(targetDir) {
-  if (!fs.existsSync(targetDir)) {
-    return [...DEFAULT_SOURCE_PATHS];
-  }
-
-  let entries = [];
-  try {
-    entries = fs.readdirSync(targetDir, { withFileTypes: true });
-  } catch {
-    return [...DEFAULT_SOURCE_PATHS];
-  }
-
-  const codeDirs = [];
-  const docDirs = [];
-  const rootFiles = [];
-
-  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-    const absolutePath = path.join(targetDir, entry.name);
-
-    if (entry.isDirectory()) {
-      if (INIT_SKIP_DIRECTORIES.has(entry.name)) {
-        continue;
-      }
-      if (!directoryContainsInterestingFiles(absolutePath)) {
-        continue;
-      }
-
-      const bucket = ROOT_DOC_PATHS.has(entry.name) ? docDirs : codeDirs;
-      bucket.push(toPosixPath(entry.name));
-      continue;
-    }
-
-    if (entry.isFile() && isInterestingSourceFile(entry.name)) {
-      rootFiles.push(toPosixPath(entry.name));
-    }
-  }
-
-  const readmeFiles = rootFiles.filter((filePath) => /^readme(\.|$)/i.test(path.basename(filePath)));
-  const nonReadmeRootFiles = rootFiles.filter((filePath) => !readmeFiles.includes(filePath));
-  const detected = [
-    ...codeDirs,
-    ...nonReadmeRootFiles,
-    ...docDirs,
-    ".context/notes",
-    ".context/decisions",
-    ...readmeFiles
-  ];
-  const uniqueDetected = [...new Set(detected)];
-  const hasConcreteRepoContent = uniqueDetected.some((value) => !value.startsWith(".context/"));
-  return hasConcreteRepoContent ? uniqueDetected : [...DEFAULT_SOURCE_PATHS];
+  return [...DEFAULT_SOURCE_PATHS];
 }
 
 function buildInitialConfig(targetDir) {
@@ -418,12 +261,10 @@ function buildInitialConfig(targetDir) {
     "  - RULE",
     "  - CODE",
     "  - WIKI",
-    "# graph weight is low because graph degree mostly measures how many rules",
-    "# constrain an entity (docs are hubs, leaf code is not). Tuned as a pair with",
-    "# the midrank-percentile graph_score.",
+    "# Tuned together with the midrank-percentile graph_score in searchResults.ts.",
     "ranking:",
-    "  semantic: 0.55",
-    "  graph: 0.10",
+    "  semantic: 0.40",
+    "  graph: 0.25",
     "  trust: 0.20",
     "  recency: 0.15",
     "runtime:",
@@ -645,6 +486,10 @@ function installCodexAgentsSection(targetDir) {
   const startMarker = "<!-- cortex:auto:start -->";
   const endMarker = "<!-- cortex:auto:end -->";
   const section = `## Cortex Auto Workflow
+- Use the \`using-cortex\` skill if available; otherwise follow the commands below.
+- Search before answering code questions: \`cortex search "<query>" --json\`; never answer from memory.
+- Check \`cortex rules --json\` before suggesting changes and \`cortex impact "<query>" --json\` before refactors.
+- Review changed files with \`cortex pattern-evidence <file> --json\` before finalizing.
 - Run \`cortex update\` before completing substantial code changes.
 - If background sync is enabled, check with \`cortex watch status\`.`;
   const changed = upsertSectionByMarkers(agentsPath, startMarker, endMarker, section);
@@ -956,12 +801,31 @@ async function ensureProjectInitializedForMcp(targetDir) {
   }
 }
 
+// The session bootstrap hook caches index status for 10 minutes; drop the
+// cache whenever a command may have changed the index so new sessions never
+// see a stale "no index"/"index is old" verdict.
+const INDEX_MUTATING_COMMANDS = new Set(["bootstrap", "update", "refresh", "ingest", "embed", "graph-load"]);
+
+function invalidateSessionStatusCache(cwd) {
+  try {
+    fs.rmSync(path.join(cwd, ".context", "cache", "session-status.json"), { force: true });
+  } catch {
+    // best effort: a stale cache only delays the status refresh
+  }
+}
+
 async function runContextCommand(cwd, contextArgs) {
   const contextScript = path.join(cwd, CONTEXT_SCRIPTS_REL, "context.sh");
   if (!fs.existsSync(contextScript)) {
     throw new Error(`Missing ${contextScript}. Run 'cortex init' first.`);
   }
-  await runCommand("bash", [contextScript, ...contextArgs], cwd);
+  try {
+    await runCommand("bash", [contextScript, ...contextArgs], cwd);
+  } finally {
+    if (INDEX_MUTATING_COMMANDS.has(contextArgs[0])) {
+      invalidateSessionStatusCache(cwd);
+    }
+  }
 }
 
 async function run() {
@@ -1588,7 +1452,7 @@ async function runEnterpriseInstall(args) {
 }
 
 const RUN_CLIS = new Set(["claude", "codex", "copilot"]);
-const QUERY_COMMANDS = new Set(["search", "related", "impact", "rules", "explain"]);
+const QUERY_COMMANDS = new Set(["search", "related", "impact", "rules", "explain", "pattern-evidence"]);
 
 async function runRunCommand(args) {
   const sub = args[0];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.2.4",
+  "version": "2.4.0",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",
@@ -64,7 +64,7 @@
   ],
   "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/ingest-parallel.test.mjs tests/ingest-worker-crash.test.mjs tests/javascript-parser.test.mjs tests/markdown-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 tests/bootstrapbench-run.test.mjs tests/bootstrapbench-stats.test.mjs tests/bootstrapbench-aggregate.test.mjs tests/bootstrapbench-cleanup.test.mjs tests/query-cli-shim.test.mjs",
+    "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.test.mjs tests/ingest-parallel.test.mjs tests/ingest-worker-crash.test.mjs tests/javascript-parser.test.mjs tests/markdown-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 tests/bootstrapbench-run.test.mjs tests/bootstrapbench-stats.test.mjs tests/bootstrapbench-aggregate.test.mjs tests/bootstrapbench-cleanup.test.mjs tests/bootstrapbench-query-packs.test.mjs tests/query-cli-shim.test.mjs tests/session-bootstrap.test.mjs tests/plugin-skills.test.mjs tests/plugin-manifests.test.mjs",
     "release:sync-version": "node scripts/sync-release-version.mjs",
     "release:check-version-sync": "node scripts/sync-release-version.mjs --check",
     "prepublishOnly": "echo 'Ready to publish to npm'"

package/scaffold/mcp/package-lock.json

@@ -742,9 +742,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/eventemitter": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.0.tgz",
-      "integrity": "sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz",
+      "integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==",
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/fetch": {
@@ -762,12 +762,6 @@
       "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==",
       "license": "BSD-3-Clause"
     },
-    "node_modules/@protobufjs/inquire": {
-      "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": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz",
@@ -1865,9 +1859,19 @@
       }
     },
     "node_modules/js-yaml": {
-      "version": "4.1.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
-      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.2.0.tgz",
+      "integrity": "sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/nodeca"
+        }
+      ],
       "license": "MIT",
       "dependencies": {
         "argparse": "^2.0.1"
@@ -2128,24 +2132,23 @@
       "license": "MIT"
     },
     "node_modules/protobufjs": {
-      "version": "7.5.9",
-      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.9.tgz",
-      "integrity": "sha512-Od4muIm3HW1AouyHF5lONOf1FWo3hY1NbFDoy191X9GzhpgW1clCoaFjfVs2rKJNFYpTNJbje4cbAIDBZJ63ZA==",
+      "version": "7.6.4",
+      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.6.4.tgz",
+      "integrity": "sha512-RJJPTTpvFfHcWLkIa2JFWK4XvtSzS0yEWDmunqHXli1h3JlkbcQZXDZdcWxv+JK3Xsl5/UFDPZ0iGm7DAengYw==",
       "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/eventemitter": "^1.1.1",
         "@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"
+        "long": "^5.3.2"
       },
       "engines": {
         "node": ">=12.0.0"
@@ -2539,9 +2542,9 @@
       }
     },
     "node_modules/tar": {
-      "version": "7.5.11",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.11.tgz",
-      "integrity": "sha512-ChjMH33/KetonMTAtpYdgUFr0tbz69Fp2v7zWxQfYZX4g5ZN2nOBXm1R2xyA+lMIKrLKIoKAwFj93jE/avX9cQ==",
+      "version": "7.5.16",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.16.tgz",
+      "integrity": "sha512-56adEpPMouktRlBLXiaYFFzZ/3+JXa8P9n7WbR+ibIjtviN55mEaOkiysCnPnWm+7kkui1Dn8J9l+g6zV8731w==",
       "license": "BlueOak-1.0.0",
       "dependencies": {
         "@isaacs/fs-minipass": "^4.0.0",

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

@@ -1,7 +1,9 @@
 import { runContextRules } from "../rules.js";
+import { runPatternEvidence } from "../patternEvidence.js";
 import { runContextImpact, runContextRelated, runContextSearch } from "../search.js";
 import type {
   ImpactParams,
+  PatternEvidenceParams,
   RelatedParams,
   RelationType,
   RulesParams,
@@ -29,7 +31,7 @@ type JsonEnvelope = {
   };
 };
 
-const QUERY_COMMANDS = new Set(["search", "related", "impact", "rules", "explain"]);
+const QUERY_COMMANDS = new Set(["search", "related", "impact", "rules", "explain", "pattern-evidence"]);
 
 const ENTITY_ID_PREFIXES = [
   "file:",
@@ -66,6 +68,8 @@ export async function runQueryCommand(args: string[]): Promise<void> {
         return await runRules(rest);
       case "explain":
         return await runExplain(rest);
+      case "pattern-evidence":
+        return await runPatternEvidenceCommand(rest);
       default:
         throw new Error(`Unknown query command: ${command}`);
     }
@@ -93,6 +97,7 @@ function printHelp(): void {
     "  cortex impact <query-or-entity-id> [--entity-id <id>] [--query <q>] [--depth <n>] [--top-k <n>] [--json]",
     "  cortex rules [--scope <scope>] [--include-inactive] [--json]",
     "  cortex explain <query-or-entity-id> [--top-k <n>] [--json]",
+    "  cortex pattern-evidence <file-path|entity-id> [--query <text>] [--top-k <n>] [--json]",
     "",
     "These commands read the local Cortex graph and emit MCP-equivalent data with --json.",
   ];
@@ -157,7 +162,11 @@ function parsePositiveIntFlag(
   if (typeof raw !== "string" || raw.trim().length === 0) {
     throw new Error(`--${name} requires a numeric value`);
   }
-  const parsed = Number.parseInt(raw, 10);
+  const normalized = raw.trim();
+  if (!/^[1-9]\d*$/.test(normalized)) {
+    throw new Error(`--${name} must be an integer from 1 to ${max}`);
+  }
+  const parsed = Number(normalized);
   if (!Number.isInteger(parsed) || parsed <= 0 || parsed > max) {
     throw new Error(`--${name} must be an integer from 1 to ${max}`);
   }
@@ -453,3 +462,28 @@ async function runExplain(args: string[]): Promise<void> {
   }
   printSummary("explain", data);
 }
+
+async function runPatternEvidenceCommand(args: string[]): Promise<void> {
+  const { flags, rest } = parseArgs(args);
+  const target = optionalString(flags, "target") ?? positionalText(rest, "file-path-or-entity-id");
+  const input: PatternEvidenceParams = {
+    target,
+    query: optionalString(flags, "query"),
+    top_k: parsePositiveIntFlag(flags, "top-k", 3, 10),
+    include_deprecated: isFlagEnabled(flags, "include-deprecated"),
+  };
+  const data = await runPatternEvidence(input);
+  if (isFlagEnabled(flags, "json")) {
+    emitEnvelope("pattern-evidence", input, data);
+    return;
+  }
+
+  const tiers = Array.isArray(data.tiers) ? data.tiers : [];
+  process.stdout.write(`pattern-evidence: local_pattern_found=${String(data.local_pattern_found)}\n`);
+  for (const value of tiers) {
+    if (!value || typeof value !== "object") continue;
+    const tier = value as Record<string, unknown>;
+    const evidence = Array.isArray(tier.evidence) ? tier.evidence : [];
+    process.stdout.write(`- ${String(tier.name ?? "")}: ${evidence.length}\n`);
+  }
+}