@a-company/paradigm 3.14.1 → 3.15.0

package/dist/{chunk-O5ZO5LSW.js → chunk-D4VBBKGV.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // ../paradigm-mcp/src/tools/reindex.ts
-import * as fs8 from "fs";
-import * as path9 from "path";
-import * as yaml7 from "js-yaml";
+import * as fs9 from "fs";
+import * as path10 from "path";
+import * as yaml8 from "js-yaml";
 
 // ../paradigm-mcp/node_modules/.pnpm/@a-company+premise-core@0.2.0_typescript@5.9.3/node_modules/@a-company/premise-core/dist/index.js
 import * as yaml3 from "js-yaml";
@@ -1991,8 +1991,8 @@ var SessionTracker = class {
    * Extract resource type from URI
    */
   extractResourceType(uri) {
-    const path10 = uri.replace("paradigm://", "");
-    const firstPart = path10.split("/")[0];
+    const path11 = uri.replace("paradigm://", "");
+    const firstPart = path11.split("/")[0];
     return firstPart || "unknown";
   }
   /**
@@ -4389,8 +4389,8 @@ async function getAffectedPersonas(rootDir, symbol) {
   }
   return results;
 }
-function deepGet(obj, path10) {
-  const parts = path10.split(/[.\[\]]+/).filter(Boolean);
+function deepGet(obj, path11) {
+  const parts = path11.split(/[.\[\]]+/).filter(Boolean);
   let current = obj;
   for (const part of parts) {
     if (current == null || typeof current !== "object") return void 0;
@@ -4558,6 +4558,341 @@ async function validateAgainstSentinel(persona, options = {}) {
   };
 }
 
+// ../paradigm-mcp/src/utils/protocol-loader.ts
+import * as fs8 from "fs";
+import * as path9 from "path";
+import * as yaml7 from "js-yaml";
+var PROTOCOLS_DIR = ".paradigm/protocols";
+var INDEX_FILE2 = "index.yaml";
+async function loadProtocols(rootDir) {
+  const protocolsDir = path9.join(rootDir, PROTOCOLS_DIR);
+  if (!fs8.existsSync(protocolsDir)) {
+    return [];
+  }
+  const files = fs8.readdirSync(protocolsDir).filter((f) => f.endsWith(".protocol")).sort();
+  const protocols = [];
+  for (const file of files) {
+    try {
+      const content = fs8.readFileSync(path9.join(protocolsDir, file), "utf8");
+      const protocol = yaml7.load(content);
+      if (protocol?.id && protocol?.name) {
+        protocols.push(protocol);
+      }
+    } catch {
+    }
+  }
+  return protocols;
+}
+async function loadProtocol(rootDir, id) {
+  const slug = id.replace(/^P-/, "");
+  const filePath = path9.join(rootDir, PROTOCOLS_DIR, `${slug}.protocol`);
+  if (fs8.existsSync(filePath)) {
+    try {
+      const content = fs8.readFileSync(filePath, "utf8");
+      return yaml7.load(content);
+    } catch {
+      return null;
+    }
+  }
+  const protocols = await loadProtocols(rootDir);
+  return protocols.find((p) => p.id === id) || null;
+}
+async function loadProtocolIndex(rootDir) {
+  const indexPath = path9.join(rootDir, PROTOCOLS_DIR, INDEX_FILE2);
+  if (!fs8.existsSync(indexPath)) {
+    return null;
+  }
+  try {
+    const content = fs8.readFileSync(indexPath, "utf8");
+    return yaml7.load(content);
+  } catch {
+    return null;
+  }
+}
+async function searchProtocols(rootDir, task, limit = 3) {
+  const protocols = await loadProtocols(rootDir);
+  if (protocols.length === 0) return [];
+  const keywords = tokenize(task);
+  if (keywords.length === 0) return [];
+  const scored = [];
+  for (const protocol of protocols) {
+    let score = 0;
+    for (const trigger of protocol.trigger) {
+      const triggerLower = trigger.toLowerCase();
+      for (const kw of keywords) {
+        if (triggerLower.includes(kw)) {
+          score += 3;
+        }
+      }
+    }
+    for (const tag of protocol.tags) {
+      const tagLower = tag.toLowerCase();
+      for (const kw of keywords) {
+        if (tagLower.includes(kw) || kw.includes(tagLower)) {
+          score += 2;
+        }
+      }
+    }
+    const nameLower = protocol.name.toLowerCase();
+    const descLower = protocol.description.toLowerCase();
+    for (const kw of keywords) {
+      if (nameLower.includes(kw)) score += 1;
+      if (descLower.includes(kw)) score += 1;
+    }
+    for (const step of protocol.steps) {
+      if (step.notes) {
+        const notesLower = step.notes.toLowerCase();
+        for (const kw of keywords) {
+          if (notesLower.includes(kw)) score += 0.5;
+        }
+      }
+    }
+    if (score > 0) {
+      scored.push({ protocol, score });
+    }
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit);
+}
+async function recordProtocol(rootDir, protocol) {
+  const protocolsDir = path9.join(rootDir, PROTOCOLS_DIR);
+  if (!fs8.existsSync(protocolsDir)) {
+    fs8.mkdirSync(protocolsDir, { recursive: true });
+  }
+  const slug = slugify(protocol.name);
+  const id = `P-${slug}`;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const full = {
+    id,
+    name: protocol.name,
+    description: protocol.description,
+    trigger: protocol.trigger,
+    tags: protocol.tags,
+    symbols: protocol.symbols || [],
+    exemplar: protocol.exemplar,
+    steps: protocol.steps,
+    recorded_from: protocol.recorded_from,
+    recorded_at: now,
+    last_verified: now,
+    verified_by: protocol.verified_by || "claude-opus-4-6",
+    status: "current"
+  };
+  const filePath = path9.join(protocolsDir, `${slug}.protocol`);
+  fs8.writeFileSync(filePath, yaml7.dump(full, { lineWidth: -1, noRefs: true }), "utf8");
+  return id;
+}
+async function updateProtocol(rootDir, id, partial, refresh = false) {
+  const protocol = await loadProtocol(rootDir, id);
+  if (!protocol) return false;
+  if (partial.name !== void 0) protocol.name = partial.name;
+  if (partial.description !== void 0) protocol.description = partial.description;
+  if (partial.trigger !== void 0) protocol.trigger = partial.trigger;
+  if (partial.tags !== void 0) protocol.tags = partial.tags;
+  if (partial.symbols !== void 0) protocol.symbols = partial.symbols;
+  if (partial.exemplar !== void 0) protocol.exemplar = partial.exemplar;
+  if (partial.steps !== void 0) protocol.steps = partial.steps;
+  if (partial.status !== void 0) protocol.status = partial.status;
+  if (partial.verified_by !== void 0) protocol.verified_by = partial.verified_by;
+  if (refresh) {
+    protocol.last_verified = (/* @__PURE__ */ new Date()).toISOString();
+    protocol.verified_by = partial.verified_by || "claude-opus-4-6";
+  }
+  const slug = id.replace(/^P-/, "");
+  const filePath = path9.join(rootDir, PROTOCOLS_DIR, `${slug}.protocol`);
+  fs8.writeFileSync(filePath, yaml7.dump(protocol, { lineWidth: -1, noRefs: true }), "utf8");
+  return true;
+}
+function validateProtocol(rootDir, protocol) {
+  const issues = [];
+  let status = "current";
+  if (protocol.exemplar) {
+    const exemplarPath = path9.join(rootDir, protocol.exemplar);
+    if (!fs8.existsSync(exemplarPath)) {
+      issues.push(`Exemplar missing: ${protocol.exemplar}`);
+      status = "broken";
+    } else {
+      const stat = fs8.statSync(exemplarPath);
+      if (stat.mtime.toISOString() > protocol.last_verified) {
+        issues.push(`Exemplar modified since last verified: ${protocol.exemplar}`);
+        if (status !== "broken") status = "stale";
+      }
+    }
+  }
+  for (const step of protocol.steps) {
+    if (step.template_from) {
+      const templatePath = path9.join(rootDir, step.template_from);
+      if (!fs8.existsSync(templatePath)) {
+        issues.push(`Template file missing: ${step.template_from}`);
+        status = "broken";
+      }
+    }
+    if (step.action === "modify" && step.target) {
+      const targetPath = path9.join(rootDir, step.target);
+      if (!step.target.includes("{") && !fs8.existsSync(targetPath)) {
+        issues.push(`Modify target missing: ${step.target}`);
+        status = "broken";
+      }
+    }
+  }
+  return { status, issues };
+}
+async function rebuildProtocolIndex(rootDir) {
+  const protocols = await loadProtocols(rootDir);
+  const entries = [];
+  let current = 0;
+  let stale = 0;
+  let broken = 0;
+  for (const protocol of protocols) {
+    const validation = validateProtocol(rootDir, protocol);
+    if (protocol.status !== validation.status) {
+      protocol.status = validation.status;
+      const slug = protocol.id.replace(/^P-/, "");
+      const filePath = path9.join(rootDir, PROTOCOLS_DIR, `${slug}.protocol`);
+      if (fs8.existsSync(filePath)) {
+        fs8.writeFileSync(filePath, yaml7.dump(protocol, { lineWidth: -1, noRefs: true }), "utf8");
+      }
+    }
+    switch (validation.status) {
+      case "current":
+        current++;
+        break;
+      case "stale":
+        stale++;
+        break;
+      case "broken":
+        broken++;
+        break;
+    }
+    entries.push({
+      id: protocol.id,
+      name: protocol.name,
+      status: validation.status,
+      last_verified: protocol.last_verified,
+      trigger: protocol.trigger,
+      tags: protocol.tags
+    });
+  }
+  const index = {
+    version: "1.0",
+    generated: (/* @__PURE__ */ new Date()).toISOString(),
+    protocols: entries,
+    health: {
+      total: protocols.length,
+      current,
+      stale,
+      broken
+    }
+  };
+  const protocolsDir = path9.join(rootDir, PROTOCOLS_DIR);
+  if (protocols.length > 0) {
+    if (!fs8.existsSync(protocolsDir)) {
+      fs8.mkdirSync(protocolsDir, { recursive: true });
+    }
+    const indexPath = path9.join(protocolsDir, INDEX_FILE2);
+    fs8.writeFileSync(indexPath, yaml7.dump(index, { lineWidth: -1, noRefs: true }), "utf8");
+  }
+  return index;
+}
+function detectProtocolSuggestion(rootDir, filesCreated, filesModified) {
+  if (!filesCreated || filesCreated.length < 2) return null;
+  const dirGroups = {};
+  for (const file of filesCreated) {
+    const dir = path9.dirname(file);
+    if (!dirGroups[dir]) dirGroups[dir] = [];
+    dirGroups[dir].push(file);
+  }
+  for (const [dir, created] of Object.entries(dirGroups)) {
+    if (created.length < 2) continue;
+    const absDir = path9.join(rootDir, dir);
+    if (!fs8.existsSync(absDir)) continue;
+    const existing = fs8.readdirSync(absDir).filter((f) => {
+      const ext = path9.extname(f);
+      return [".ts", ".tsx", ".js", ".jsx", ".rs", ".py"].includes(ext);
+    });
+    const preExisting = existing.filter((f) => !created.some((c) => path9.basename(c) === f));
+    if (preExisting.length > 0) {
+      const exemplar = path9.join(dir, preExisting[0]);
+      const steps = [
+        ...created.map((f) => ({ action: "create", target: f })),
+        ...filesModified.map((f) => ({ action: "modify", target: f }))
+      ];
+      return {
+        hint: `This session created ${created.length} new files in ${dir}/ following existing patterns. Consider recording a protocol.`,
+        draft: {
+          name: `Add a ${path9.basename(dir).replace(/s$/, "")}`,
+          exemplar,
+          steps
+        }
+      };
+    }
+  }
+  return null;
+}
+function tokenize(text) {
+  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length > 1).filter((w) => !STOP_WORDS.has(w));
+}
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "to",
+  "of",
+  "in",
+  "for",
+  "on",
+  "with",
+  "at",
+  "by",
+  "from",
+  "it",
+  "this",
+  "that",
+  "and",
+  "or",
+  "but",
+  "if",
+  "then",
+  "so",
+  "as",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "can",
+  "could",
+  "should",
+  "may",
+  "might",
+  "must",
+  "shall",
+  "i",
+  "me",
+  "my",
+  "we",
+  "our",
+  "you",
+  "your",
+  "he",
+  "she",
+  "how",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "whom"
+]);
+function slugify(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
 // ../paradigm-mcp/src/tools/reindex.ts
 var SYMBOL_CATEGORIES = {
   "@": { category: "features", prefix: "@" },
@@ -4646,10 +4981,10 @@ async function rebuildStaticFiles(rootDir, ctx) {
   } else {
     aggregation = await aggregateFromDirectory(rootDir);
   }
-  const projectName = ctx?.projectName || path9.basename(rootDir);
-  const paradigmDir = path9.join(rootDir, ".paradigm");
-  if (!fs8.existsSync(paradigmDir)) {
-    fs8.mkdirSync(paradigmDir, { recursive: true });
+  const projectName = ctx?.projectName || path10.basename(rootDir);
+  const paradigmDir = path10.join(rootDir, ".paradigm");
+  if (!fs9.existsSync(paradigmDir)) {
+    fs9.mkdirSync(paradigmDir, { recursive: true });
   }
   const scanIndex = generateScanIndex(
     {
@@ -4659,22 +4994,22 @@ async function rebuildStaticFiles(rootDir, ctx) {
     },
     { projectName }
   );
-  const scanIndexPath = path9.join(paradigmDir, "scan-index.json");
-  fs8.writeFileSync(scanIndexPath, serializeScanIndex(scanIndex), "utf8");
+  const scanIndexPath = path10.join(paradigmDir, "scan-index.json");
+  fs9.writeFileSync(scanIndexPath, serializeScanIndex(scanIndex), "utf8");
   filesWritten.push(".paradigm/scan-index.json");
   const navigatorData = buildNavigatorData(rootDir, aggregation);
-  const navigatorPath = path9.join(paradigmDir, "navigator.yaml");
-  fs8.writeFileSync(
+  const navigatorPath = path10.join(paradigmDir, "navigator.yaml");
+  fs9.writeFileSync(
     navigatorPath,
-    yaml7.dump(navigatorData, { indent: 2, lineWidth: 120, noRefs: true, sortKeys: false }),
+    yaml8.dump(navigatorData, { indent: 2, lineWidth: 120, noRefs: true, sortKeys: false }),
     "utf8"
   );
   filesWritten.push(".paradigm/navigator.yaml");
   const flowIndex = generateFlowIndex(rootDir, aggregation.purposeFiles);
   let flowCount = 0;
   if (flowIndex && Object.keys(flowIndex.flows).length > 0) {
-    const flowIndexPath = path9.join(paradigmDir, "flow-index.json");
-    fs8.writeFileSync(flowIndexPath, JSON.stringify(flowIndex, null, 2), "utf8");
+    const flowIndexPath = path10.join(paradigmDir, "flow-index.json");
+    fs9.writeFileSync(flowIndexPath, JSON.stringify(flowIndex, null, 2), "utf8");
     filesWritten.push(".paradigm/flow-index.json");
     flowCount = Object.keys(flowIndex.flows).length;
   }
@@ -4706,6 +5041,15 @@ async function rebuildStaticFiles(rootDir, ctx) {
     }
   } catch {
   }
+  let protocolHealth;
+  try {
+    const protocolIndex = await rebuildProtocolIndex(rootDir);
+    if (protocolIndex.health.total > 0) {
+      protocolHealth = protocolIndex.health;
+      filesWritten.push(".paradigm/protocols/index.yaml");
+    }
+  } catch {
+  }
   const breakdown = {};
   for (const sym of aggregation.symbols) {
     breakdown[sym.type] = (breakdown[sym.type] || 0) + 1;
@@ -4717,7 +5061,8 @@ async function rebuildStaticFiles(rootDir, ctx) {
     breakdown,
     flowCount,
     aspectGraphStats,
-    personaCount
+    personaCount,
+    protocolHealth
   };
 }
 function buildNavigatorData(rootDir, aggregation) {
@@ -4733,7 +5078,7 @@ function buildNavigatorData(rootDir, aggregation) {
 function buildStructure(rootDir) {
   const structure = {};
   for (const [category, patterns] of Object.entries(DIRECTORY_PATTERNS)) {
-    const existingPaths = patterns.filter((p) => fs8.existsSync(path9.join(rootDir, p)));
+    const existingPaths = patterns.filter((p) => fs9.existsSync(path10.join(rootDir, p)));
     if (existingPaths.length > 0) {
       const symbolInfo = Object.values(SYMBOL_CATEGORIES).find((s) => s.category === category);
       structure[category] = { paths: existingPaths, symbol: symbolInfo?.prefix || "@" };
@@ -4744,7 +5089,7 @@ function buildStructure(rootDir) {
 function buildKeyFiles(rootDir) {
   const keyFiles = {};
   for (const [category, patterns] of Object.entries(KEY_FILE_PATTERNS)) {
-    const existingPaths = patterns.filter((p) => fs8.existsSync(path9.join(rootDir, p)));
+    const existingPaths = patterns.filter((p) => fs9.existsSync(path10.join(rootDir, p)));
     if (existingPaths.length > 0) {
       keyFiles[category] = existingPaths;
     }
@@ -4760,10 +5105,10 @@ function buildSkipPatterns(rootDir) {
     unless_testing: [...DEFAULT_SKIP_PATTERNS.unless_testing],
     unless_docs: [...DEFAULT_SKIP_PATTERNS.unless_docs]
   };
-  const gitignorePath = path9.join(rootDir, ".gitignore");
-  if (fs8.existsSync(gitignorePath)) {
+  const gitignorePath = path10.join(rootDir, ".gitignore");
+  if (fs9.existsSync(gitignorePath)) {
     try {
-      const content = fs8.readFileSync(gitignorePath, "utf8");
+      const content = fs9.readFileSync(gitignorePath, "utf8");
       const gitignorePatterns = content.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#")).filter(
         (line) => line.endsWith("/") || line.includes("*") || ["node_modules", "dist", "build", ".cache"].some((p) => line.includes(p))
       ).slice(0, 20);
@@ -4812,11 +5157,11 @@ function buildSymbolMap(symbols, purposeFiles, _rootDir) {
       symbolMap[symbolId] = symbol.filePath;
     } else {
       const matchingPurpose = purposeFiles.find((pf) => {
-        const dir = path9.dirname(pf);
+        const dir = path10.dirname(pf);
         return dir.toLowerCase().includes(symbol.id.toLowerCase());
       });
       if (matchingPurpose) {
-        symbolMap[symbolId] = path9.dirname(matchingPurpose) + "/";
+        symbolMap[symbolId] = path10.dirname(matchingPurpose) + "/";
       }
     }
   }
@@ -4827,8 +5172,8 @@ function generateFlowIndex(rootDir, purposeFiles) {
   const symbolToFlows = {};
   for (const filePath of purposeFiles) {
     try {
-      const content = fs8.readFileSync(filePath, "utf8");
-      const data = yaml7.load(content);
+      const content = fs9.readFileSync(filePath, "utf8");
+      const data = yaml8.load(content);
       if (!data?.flows) continue;
       if (Array.isArray(data.flows)) {
         for (const flowItem of data.flows) {
@@ -4841,7 +5186,7 @@ function generateFlowIndex(rootDir, purposeFiles) {
               id: flowId,
               description: flow.description || "",
               steps,
-              definedIn: path9.relative(rootDir, filePath)
+              definedIn: path10.relative(rootDir, filePath)
             };
             indexFlowSymbols(flowId, steps, symbolToFlows);
           }
@@ -4857,7 +5202,7 @@ function generateFlowIndex(rootDir, purposeFiles) {
               trigger: flowDef.trigger,
               steps,
               validation: flowDef.validation,
-              definedIn: path9.relative(rootDir, filePath)
+              definedIn: path10.relative(rootDir, filePath)
             };
             indexFlowSymbols(flowId, steps, symbolToFlows);
           }
@@ -4965,6 +5310,14 @@ export {
   getPersonaCoverage,
   getAffectedPersonas,
   validateAgainstSentinel,
+  loadProtocols,
+  loadProtocol,
+  loadProtocolIndex,
+  searchProtocols,
+  recordProtocol,
+  updateProtocol,
+  validateProtocol,
+  detectProtocolSuggestion,
   getReindexToolsList,
   handleReindexTool,
   rebuildStaticFiles

package/dist/mcp.js

@@ -36,6 +36,7 @@ import {
   createPersona,
   deleteLoreEntry,
   deletePersona,
+  detectProtocolSuggestion,
   findPurposeFiles,
   getAffectedPersonas,
   getAllEdgesFor,
@@ -66,6 +67,9 @@ import {
   loadLoreTimeline,
   loadPersona,
   loadPersonas,
+  loadProtocol,
+  loadProtocolIndex,
+  loadProtocols,
   openAspectGraph,
   parseGateConfig,
   parsePurposeFileDetailed,
@@ -73,7 +77,9 @@ import {
   recordGlobalAntipattern,
   recordGlobalDecision,
   recordLoreEntry,
+  recordProtocol,
   removeStep,
+  searchProtocols,
   searchSymbols,
   serializePurposeFile,
   toolCache,
@@ -81,10 +87,12 @@ import {
   trackToolCall,
   updateLoreEntry,
   updatePersona,
+  updateProtocol,
   validateAgainstSentinel,
   validatePersona,
+  validateProtocol,
   validatePurposeFile
-} from "./chunk-O5ZO5LSW.js";
+} from "./chunk-D4VBBKGV.js";
 import {
   getPluginUpdateNotice,
   schedulePluginUpdateCheck
@@ -8574,6 +8582,17 @@ async function handleLoreTool(name, args, ctx) {
       };
       const id = await recordLoreEntry(ctx.rootDir, entry);
       getSessionTracker().setLastLoreEntryId(id);
+      let protocol_suggestion = null;
+      try {
+        if (files_created && files_created.length >= 2) {
+          protocol_suggestion = detectProtocolSuggestion(
+            ctx.rootDir,
+            files_created,
+            files_modified || []
+          );
+        }
+      } catch {
+      }
       return {
         handled: true,
         text: JSON.stringify({
@@ -8581,7 +8600,8 @@ async function handleLoreTool(name, args, ctx) {
           id,
           type,
           title,
-          message: "Lore entry recorded successfully"
+          message: "Lore entry recorded successfully",
+          ...protocol_suggestion ? { protocol_suggestion } : {}
         })
       };
     }
@@ -11553,6 +11573,364 @@ async function handlePersonaTool(name, args, ctx) {
   }
 }
 
+// ../paradigm-mcp/src/tools/protocols.ts
+function getProtocolsToolsList() {
+  return [
+    {
+      name: "paradigm_protocol_search",
+      description: "Search for protocols matching a task description. Call BEFORE exploring the codebase \u2014 if a matching protocol exists, follow its steps instead of discovering the pattern from scratch. Returns top matches with steps, exemplar, and freshness info. ~200 tokens.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task: {
+            type: "string",
+            description: 'Task description to search for (e.g., "add a new page", "add API route")'
+          },
+          limit: {
+            type: "number",
+            description: "Maximum results (default: 3)"
+          }
+        },
+        required: ["task"]
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false
+      }
+    },
+    {
+      name: "paradigm_protocol_get",
+      description: "Get a specific protocol by ID with full details and freshness check. ~300 tokens.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string",
+            description: 'Protocol ID (e.g., "P-add-view")'
+          }
+        },
+        required: ["id"]
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false
+      }
+    },
+    {
+      name: "paradigm_protocol_record",
+      description: "Record a new protocol after completing repeatable work. Captures the steps you followed so future agents can skip exploration. ~100 tokens.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: 'Protocol name (e.g., "Add a new view")'
+          },
+          description: {
+            type: "string",
+            description: "What this protocol accomplishes"
+          },
+          trigger: {
+            type: "array",
+            items: { type: "string" },
+            description: 'Phrases that should match this protocol (e.g., ["add view", "new page"])'
+          },
+          tags: {
+            type: "array",
+            items: { type: "string" },
+            description: 'Classification tags (e.g., ["ui", "frontend"])'
+          },
+          symbols: {
+            type: "array",
+            items: { type: "string" },
+            description: 'Paradigm symbols involved (e.g., ["#logs-view"])'
+          },
+          exemplar: {
+            type: "string",
+            description: 'Canonical file to study for this pattern (e.g., "ui/src/views/LogsView.tsx")'
+          },
+          steps: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                action: {
+                  type: "string",
+                  enum: ["create", "modify", "run", "verify"],
+                  description: "Step action type"
+                },
+                target: {
+                  type: "string",
+                  description: "File path (supports {Name}/{name} placeholders)"
+                },
+                template_from: {
+                  type: "string",
+                  description: "File to use as template (for create actions)"
+                },
+                reference: {
+                  type: "string",
+                  description: "Where in the file to make changes (for modify actions)"
+                },
+                command: {
+                  type: "string",
+                  description: "Command to execute (for run actions)"
+                },
+                notes: {
+                  type: "string",
+                  description: "Additional guidance for this step"
+                }
+              },
+              required: ["action"]
+            },
+            description: "Ordered steps to follow"
+          },
+          recorded_from: {
+            type: "string",
+            description: 'Lore entry ID this protocol was learned from (e.g., "L-2026-03-01-001")'
+          }
+        },
+        required: ["name", "description", "trigger", "tags", "steps"]
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false
+      }
+    },
+    {
+      name: "paradigm_protocol_update",
+      description: "Update an existing protocol. Use refresh:true after successfully following a protocol to bump last_verified. ~100 tokens.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string",
+            description: 'Protocol ID to update (e.g., "P-add-view")'
+          },
+          refresh: {
+            type: "boolean",
+            description: "Set true to bump last_verified to now (use after successfully following the protocol)"
+          },
+          name: { type: "string", description: "Updated name" },
+          description: { type: "string", description: "Updated description" },
+          trigger: {
+            type: "array",
+            items: { type: "string" },
+            description: "Updated trigger phrases"
+          },
+          tags: {
+            type: "array",
+            items: { type: "string" },
+            description: "Updated tags"
+          },
+          symbols: {
+            type: "array",
+            items: { type: "string" },
+            description: "Updated symbols"
+          },
+          exemplar: { type: "string", description: "Updated exemplar path" },
+          steps: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                action: { type: "string", enum: ["create", "modify", "run", "verify"] },
+                target: { type: "string" },
+                template_from: { type: "string" },
+                reference: { type: "string" },
+                command: { type: "string" },
+                notes: { type: "string" }
+              },
+              required: ["action"]
+            },
+            description: "Updated steps"
+          }
+        },
+        required: ["id"]
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false
+      }
+    },
+    {
+      name: "paradigm_protocol_validate",
+      description: "Validate protocol references \u2014 check that referenced files exist, exemplars haven't drifted. Validates all protocols if no ID given. ~200 tokens.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: {
+            type: "string",
+            description: "Protocol ID to validate (omit to validate all)"
+          }
+        }
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false
+      }
+    }
+  ];
+}
+async function handleProtocolsTool(name, args, ctx) {
+  switch (name) {
+    case "paradigm_protocol_search": {
+      const task = args.task;
+      const limit = args.limit || 3;
+      const results = await searchProtocols(ctx.rootDir, task, limit);
+      if (results.length === 0) {
+        return {
+          handled: true,
+          text: JSON.stringify({
+            count: 0,
+            task,
+            message: "No matching protocol found. Consider recording one after completing this task."
+          })
+        };
+      }
+      return {
+        handled: true,
+        text: JSON.stringify({
+          count: results.length,
+          task,
+          matches: results.map((r) => ({
+            id: r.protocol.id,
+            name: r.protocol.name,
+            description: r.protocol.description,
+            score: r.score,
+            status: r.protocol.status,
+            exemplar: r.protocol.exemplar,
+            last_verified: r.protocol.last_verified,
+            steps: r.protocol.steps.map(summarizeStep)
+          }))
+        }, null, 2)
+      };
+    }
+    case "paradigm_protocol_get": {
+      const id = args.id;
+      const protocol = await loadProtocol(ctx.rootDir, id);
+      if (!protocol) {
+        return {
+          handled: true,
+          text: JSON.stringify({ error: `Protocol not found: ${id}` })
+        };
+      }
+      const validation = validateProtocol(ctx.rootDir, protocol);
+      return {
+        handled: true,
+        text: JSON.stringify({
+          ...protocol,
+          freshness: {
+            status: validation.status,
+            issues: validation.issues
+          }
+        }, null, 2)
+      };
+    }
+    case "paradigm_protocol_record": {
+      const steps = args.steps || [];
+      const id = await recordProtocol(ctx.rootDir, {
+        name: args.name,
+        description: args.description,
+        trigger: args.trigger || [],
+        tags: args.tags || [],
+        symbols: args.symbols || [],
+        exemplar: args.exemplar,
+        steps,
+        recorded_from: args.recorded_from,
+        verified_by: "claude-opus-4-6"
+      });
+      return {
+        handled: true,
+        text: JSON.stringify({
+          success: true,
+          id,
+          name: args.name,
+          message: "Protocol recorded successfully"
+        })
+      };
+    }
+    case "paradigm_protocol_update": {
+      const id = args.id;
+      const refresh = args.refresh;
+      const partial = {};
+      if (args.name !== void 0) partial.name = args.name;
+      if (args.description !== void 0) partial.description = args.description;
+      if (args.trigger !== void 0) partial.trigger = args.trigger;
+      if (args.tags !== void 0) partial.tags = args.tags;
+      if (args.symbols !== void 0) partial.symbols = args.symbols;
+      if (args.exemplar !== void 0) partial.exemplar = args.exemplar;
+      if (args.steps !== void 0) partial.steps = args.steps;
+      const success = await updateProtocol(ctx.rootDir, id, partial, refresh === true);
+      return {
+        handled: true,
+        text: JSON.stringify({
+          success,
+          id,
+          refreshed: refresh === true,
+          message: success ? refresh ? "Protocol updated and verified" : "Protocol updated" : `Protocol not found: ${id}`
+        })
+      };
+    }
+    case "paradigm_protocol_validate": {
+      const id = args.id;
+      if (id) {
+        const protocol = await loadProtocol(ctx.rootDir, id);
+        if (!protocol) {
+          return {
+            handled: true,
+            text: JSON.stringify({ error: `Protocol not found: ${id}` })
+          };
+        }
+        const result = validateProtocol(ctx.rootDir, protocol);
+        return {
+          handled: true,
+          text: JSON.stringify({
+            id: protocol.id,
+            name: protocol.name,
+            status: result.status,
+            issues: result.issues,
+            last_verified: protocol.last_verified
+          }, null, 2)
+        };
+      }
+      const protocols = await loadProtocols(ctx.rootDir);
+      const results = protocols.map((p) => {
+        const v = validateProtocol(ctx.rootDir, p);
+        return {
+          id: p.id,
+          name: p.name,
+          status: v.status,
+          issues: v.issues,
+          last_verified: p.last_verified
+        };
+      });
+      const health = {
+        total: results.length,
+        current: results.filter((r) => r.status === "current").length,
+        stale: results.filter((r) => r.status === "stale").length,
+        broken: results.filter((r) => r.status === "broken").length
+      };
+      return {
+        handled: true,
+        text: JSON.stringify({ protocols: results, health }, null, 2)
+      };
+    }
+    default:
+      return { handled: false, text: "" };
+  }
+}
+function summarizeStep(step) {
+  const result = {
+    action: step.action
+  };
+  if (step.target) result.target = step.target;
+  if (step.template_from) result.template_from = step.template_from;
+  if (step.reference) result.reference = step.reference;
+  if (step.command) result.command = step.command;
+  if (step.notes) result.notes = step.notes;
+  return result;
+}
+
 // ../paradigm-mcp/src/tools/fallback-grep.ts
 import * as path23 from "path";
 import { execSync as execSync3 } from "child_process";
@@ -11844,6 +12222,8 @@ function registerTools(server, getContext2, reloadContext2) {
           // Assessment loop tools
           ...getAssessmentToolsList(),
           ...getPersonaToolsList(),
+          // Protocol tools
+          ...getProtocolsToolsList(),
           // Plugin update check
           {
             name: "paradigm_plugin_check",
@@ -12226,7 +12606,7 @@ function registerTools(server, getContext2, reloadContext2) {
             };
           }
           case "paradigm_status": {
-            const text = await toolCache.getOrCompute("status", () => {
+            const text = await toolCache.getOrCompute("status", async () => {
               const counts = getSymbolCounts(ctx.index);
               const total = Object.values(counts).reduce((a, b) => a + b, 0);
               const examples = {};
@@ -12237,6 +12617,14 @@ function registerTools(server, getContext2, reloadContext2) {
               const platform2 = os.platform();
               const isWindows = platform2 === "win32";
               const shell = isWindows ? "PowerShell/CMD" : platform2 === "darwin" ? "zsh/bash" : "bash";
+              let protocols;
+              try {
+                const protocolIndex = await loadProtocolIndex(ctx.rootDir);
+                if (protocolIndex && protocolIndex.health.total > 0) {
+                  protocols = protocolIndex.health;
+                }
+              } catch {
+              }
               return JSON.stringify({
                 project: ctx.projectName,
                 symbolSystem: "v2",
@@ -12251,6 +12639,7 @@ function registerTools(server, getContext2, reloadContext2) {
                 examples,
                 hasPortalYaml: ctx.gateConfig !== null,
                 purposeFiles: ctx.aggregation.purposeFiles.length,
+                ...protocols ? { protocols } : {},
                 note: "Symbol System v2: Use tags [feature], [state], [integration], [idea] for classification",
                 environment: {
                   os: platform2,
@@ -12465,7 +12854,7 @@ Update command:
               trackToolCall(noWsText.length, name);
               return { content: [{ type: "text", text: noWsText }] };
             }
-            const { rebuildStaticFiles: rebuildStaticFiles2 } = await import("./reindex-4OOME3TT.js");
+            const { rebuildStaticFiles: rebuildStaticFiles2 } = await import("./reindex-T4N3NG73.js");
             const memberResults = [];
             for (const member of ctx.workspace.config.members) {
               const memberAbsPath = path24.resolve(path24.dirname(ctx.workspace.workspacePath), member.path);
@@ -12648,6 +13037,15 @@ Update command:
                 };
               }
             }
+            if (name.startsWith("paradigm_protocol_")) {
+              const result = await handleProtocolsTool(name, args, ctx);
+              if (result.handled) {
+                trackToolCall(result.text.length, name);
+                return {
+                  content: [{ type: "text", text: result.text }]
+                };
+              }
+            }
             if (name === "paradigm_reindex") {
               const reload = reloadContext2 || (async () => {
               });

package/dist/{reindex-4OOME3TT.js → reindex-T4N3NG73.js}

@@ -3,7 +3,7 @@ import {
   getReindexToolsList,
   handleReindexTool,
   rebuildStaticFiles
-} from "./chunk-O5ZO5LSW.js";
+} from "./chunk-D4VBBKGV.js";
 export {
   getReindexToolsList,
   handleReindexTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-company/paradigm",
-  "version": "3.14.1",
+  "version": "3.15.0",
   "description": "Unified CLI for Paradigm developer tools",
   "type": "module",
   "main": "./dist/index.js",