@a-company/paradigm 3.14.0 → 3.15.0

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,