@a-company/paradigm 3.1.6 → 3.6.0

package/dist/{accept-orchestration-CWZNCGZX.js → accept-orchestration-DIGPJVUR.js}

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 import {
   BackgroundOrchestrator
-} from "./chunk-AD2LSCHB.js";
+} from "./chunk-Y4XZWCHK.js";
 import "./chunk-6QC3YGB6.js";
-import "./chunk-WS5KM7OL.js";
+import "./chunk-HPC3JAUP.js";
+import "./chunk-6RNYVBSG.js";
 import "./chunk-PBHIFAL4.js";
-import "./chunk-TAP5N3HH.js";
+import "./chunk-CCG6KYBT.js";
 import "./chunk-PMXRGPRQ.js";
-import "./chunk-5C4SGQKH.js";
-import "./chunk-PW2EXJQT.js";
+import "./chunk-6P4IFIK2.js";
+import "./chunk-MRENOFTR.js";
 import "./chunk-IRKUEJVW.js";
 import "./chunk-5JGJACDU.js";
 import "./chunk-MO4EEYFW.js";

package/dist/{aggregate-W7Q6VIM2.js → aggregate-V4KPR3RW.js}

@@ -5,8 +5,8 @@ import {
   buildSymbolIndex,
   getSymbolCounts,
   parsePremiseFile
-} from "./chunk-5C4SGQKH.js";
-import "./chunk-PW2EXJQT.js";
+} from "./chunk-6P4IFIK2.js";
+import "./chunk-MRENOFTR.js";
 import "./chunk-IRKUEJVW.js";
 import "./chunk-MO4EEYFW.js";
 

package/dist/{beacon-B47XSTL7.js → beacon-XRXL5KZB.js}

@@ -4,8 +4,8 @@ import {
   buildSymbolIndex,
   getAllSymbols,
   getSymbolCounts
-} from "./chunk-5C4SGQKH.js";
-import "./chunk-PW2EXJQT.js";
+} from "./chunk-6P4IFIK2.js";
+import "./chunk-MRENOFTR.js";
 import "./chunk-IRKUEJVW.js";
 import {
   log

package/dist/{chunk-YCLN7WXV.js → chunk-2QNZ6PVD.js}

@@ -405,6 +405,75 @@ function generateCheckpointProtocol() {
   lines.push("");
   return lines.join("\n");
 }
+function generateHabitsSection() {
+  const lines = [];
+  lines.push("## Habits Compliance");
+  lines.push("");
+  lines.push("Paradigm tracks behavioral habits \u2014 repeatable practices that improve code quality.");
+  lines.push("");
+  lines.push("### When to Check Habits");
+  lines.push("");
+  lines.push("| Trigger | When | Tool |");
+  lines.push("|---------|------|------|");
+  lines.push('| `preflight` | Before starting implementation | `paradigm_habits_check({ trigger: "preflight" })` |');
+  lines.push('| `postflight` | After completing implementation | `paradigm_habits_check({ trigger: "postflight" })` |');
+  lines.push('| `on-stop` | Before ending a session | `paradigm_habits_check({ trigger: "on-stop" })` |');
+  lines.push("");
+  lines.push("### Key Habit Categories");
+  lines.push("");
+  lines.push("| Category | Examples |");
+  lines.push("|----------|----------|");
+  lines.push("| Discovery | Call `paradigm_ripple` before modifying symbols |");
+  lines.push("| Security | Declare gates for new routes in portal.yaml |");
+  lines.push("| Documentation | Update .purpose files for modified components |");
+  lines.push("| Quality | Record lore for sessions modifying 3+ files |");
+  lines.push("");
+  lines.push("Use `paradigm_practice_context` before modifying symbols to get habit-aware warnings.");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateLoreSection() {
+  const lines = [];
+  lines.push("## Lore Recording");
+  lines.push("");
+  lines.push("Lore captures the project timeline \u2014 sessions, decisions, milestones, and incidents.");
+  lines.push("");
+  lines.push("### When to Record Lore");
+  lines.push("");
+  lines.push("| Type | When | Example |");
+  lines.push("|------|------|---------|");
+  lines.push('| `agent-session` | After modifying 3+ files | "Added JWT auth to /api/projects" |');
+  lines.push('| `decision` | After making architectural choices | "Chose Redis over Memcached for caching" |');
+  lines.push('| `milestone` | After completing a significant feature | "v2.0 migration complete" |');
+  lines.push('| `incident` | After resolving a production issue | "Fixed OOM in payment worker" |');
+  lines.push("");
+  lines.push("### Recording");
+  lines.push("");
+  lines.push("```");
+  lines.push("paradigm_lore_record({");
+  lines.push('  type: "agent-session",');
+  lines.push('  title: "Short description of work done",');
+  lines.push('  summary: "Detailed summary of changes...",');
+  lines.push('  symbols_touched: ["#component", "^gate"]');
+  lines.push("})");
+  lines.push("```");
+  lines.push("");
+  lines.push("Use `paradigm_lore_timeline` at session start for project history orientation.");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateLlmsTxtSection() {
+  const lines = [];
+  lines.push("## llms.txt");
+  lines.push("");
+  lines.push("This project provides an `llms.txt` file at the repository root \u2014 a plain-text summary");
+  lines.push("of the project optimized for LLM consumption. It includes symbols, key files, flows,");
+  lines.push("gates, and conventions.");
+  lines.push("");
+  lines.push("Regenerate with: `paradigm sync-llms`");
+  lines.push("");
+  return lines.join("\n");
+}
 function generateFooter() {
   const lines = [];
   lines.push("---");
@@ -471,6 +540,10 @@ ${f.content}`).join("\n\n---\n\n");
       path: "paradigm-core.mdc",
       content: this.generateCoreRules(projectName, config)
     });
+    generatedFiles.push({
+      path: "paradigm-workflow.mdc",
+      content: this.generateWorkflowMdc()
+    });
     generatedFiles.push({
       path: "paradigm-symbols.mdc",
       content: this.generateSymbolRules(config)
@@ -519,6 +592,10 @@ ${f.content}`).join("\n\n---\n\n");
       path: "paradigm-flows.mdc",
       content: this.generateFlowsMdc()
     });
+    generatedFiles.push({
+      path: "paradigm-practices.mdc",
+      content: this.generatePracticesMdc()
+    });
     generatedFiles.push({
       path: "paradigm-commits.mdc",
       content: this.generateCommitsMdc()
@@ -534,6 +611,14 @@ ${f.content}`).join("\n\n---\n\n");
 
 > **Author:** Matt Canoy ([@ascend42](https://github.com/ascend42)) | **Repo:** [github.com/ascend42/a-paradigm](https://github.com/ascend42/a-paradigm) | **npm:** [@a-company/paradigm](https://www.npmjs.com/package/@a-company/paradigm)
 
+## CRITICAL RULES (Non-Negotiable)
+
+1. **You MUST update the nearest \`.purpose\` file when you change behavior.** No exceptions.
+2. **You MUST call \`paradigm_session_recover\` at session start and \`paradigm_pm_postflight\` when finishing.** See \`paradigm-workflow.mdc\` for the full protocol.
+3. **You MUST call \`paradigm_ripple\` before modifying any documented symbol.** Check impact before changing code.
+
+Violating these rules means your changes are non-compliant. The \`paradigm-workflow.mdc\` file contains the complete workflow \u2014 follow it.
+
 ` + overview + "\n\n" + generateUpdateRules(config);
   }
   /**
@@ -660,74 +745,78 @@ gate.allow('Access granted');
     }) + generateConventions(config);
   }
   /**
-   * Agent Hints - when to query CLI commands
+   * Agent Hints - MCP-first queries for AI agents
    */
   generateAgentHintsMdc() {
-    return frontmatter("Paradigm CLI queries for AI agents - prefer CLI over reading large files", {
+    return frontmatter("Paradigm MCP tool queries for AI agents - use MCP tools instead of reading large files or running CLI commands", {
       alwaysApply: true
-    }) + `# Agent CLI Queries (Token-Efficient)
+    }) + `# Agent MCP Queries (Token-Efficient)
 
-Instead of reading large context files, query Paradigm CLI on-demand for fresh, precise data.
+**Use MCP tool calls, NOT CLI commands.** MCP tools return structured data directly \u2014 no shell overhead, no parsing, no latency.
 
 ## When to Query
 
-| Before doing this... | Run this command |
-|---------------------|------------------|
-| Modifying a symbol | \`paradigm ripple #symbol --json\` |
-| Debugging an error | \`paradigm echo ERROR_CODE --json\` |
-| Starting a session | \`paradigm thread --json\` |
-| Understanding relationships | \`paradigm constellation\` |
-| Getting oriented | \`paradigm beacon --json\` |
+| Before doing this... | Call this MCP tool |
+|---------------------|-------------------|
+| Modifying a symbol | \`paradigm_ripple({ symbol: "#symbol" })\` |
+| Debugging / searching | \`paradigm_search({ query: "ERROR_CODE" })\` |
+| Starting a session | \`paradigm_session_recover()\` |
+| Understanding relationships | \`paradigm_navigate({ intent: "find", target: "#symbol" })\` |
+| Getting oriented | \`paradigm_status()\` |
+| Checking impact on flows | \`paradigm_flows_affected({ symbol: "#symbol" })\` |
+| Adding API endpoints | \`paradigm_gates_for_route({ method: "POST", path: "/api/resource" })\` |
 
 ## Query Patterns
 
 ### Before Changing Code
 
-\`\`\`bash
-# See what depends on what you're changing
-paradigm ripple #checkout --json
+\`\`\`
+// See what depends on what you're changing
+paradigm_ripple({ symbol: "#checkout" })
 
-# Output includes: upstream deps, downstream effects, flow membership
+// Returns: upstream deps, downstream effects, flow membership
 \`\`\`
 
 ### When Debugging
 
-\`\`\`bash
-# Look up error context
-paradigm echo AUTH_REQUIRED --json
+\`\`\`
+// Search for error context
+paradigm_search({ query: "AUTH_REQUIRED" })
 
-# Then check ripple effects of the related symbol
-paradigm ripple ^authenticated --json
+// Then check ripple effects of the related symbol
+paradigm_ripple({ symbol: "^authenticated" })
 \`\`\`
 
 ### Starting Work
 
-\`\`\`bash
-# Check previous session context
-paradigm thread --json
+\`\`\`
+// Load previous session context (MUST do this at session start)
+paradigm_session_recover()
 
-# Quick orientation
-paradigm beacon --json
+// Quick project orientation
+paradigm_status()
 \`\`\`
 
-### Querying Constellation
+### Finding Code Locations
 
-\`\`\`bash
-# Get specific symbol
-jq '.stars["#checkout"]' .paradigm/constellation.json
+\`\`\`
+// Find a specific symbol
+paradigm_navigate({ intent: "find", target: "#checkout" })
 
-# Find what requires a gate
-jq '[.stars | to_entries[] | select(.value.gates[]? == "^authenticated") | .key]' .paradigm/constellation.json
+// Explore an area of code
+paradigm_navigate({ intent: "explore", target: "authentication" })
 
-# List all flows
-jq '.orbits | keys' .paradigm/constellation.json
+// Get context for a task
+paradigm_navigate({ intent: "context", task: "add Apple Pay" })
 \`\`\`
 
-## Benefits
+## Why MCP Over CLI
 
+- **No shell overhead**: Direct structured responses, no \`--json\` flags or \`jq\` parsing
 - **Fresh data**: Always current, not stale from file generation
 - **Precise**: Only get the data you need
-- **Token-efficient**: ~100 tokens per query vs ~2000 upfront
+- **Token-efficient**: ~100-300 tokens per query vs ~2000 for file reads
+- **No latency**: No process spawn \u2014 MCP tools respond directly
 `;
   }
   /**
@@ -854,6 +943,97 @@ paradigm_session_stats()
 \`\`\`
 
 ${generateCheckpointProtocol()}`;
+  }
+  /**
+   * Workflow protocol - the single most important compliance file.
+   * Contains session bookends, task-size guide, essential MCP tools, and non-negotiable rules.
+   */
+  generateWorkflowMdc() {
+    return frontmatter("Paradigm workflow protocol - MUST follow for every task. Session bookends, task-size compliance, essential MCP tools.", {
+      alwaysApply: true
+    }) + `# Paradigm Workflow Protocol
+
+**This file defines the non-negotiable workflow for every task. Follow it.**
+
+## Session Bookends (MUST Do)
+
+### Session Start
+\`\`\`
+paradigm_session_recover()
+\`\`\`
+Call this FIRST in every session. Returns previous context, modified symbols, and suggestions.
+
+### Session End
+\`\`\`
+paradigm_pm_postflight({ summary: "what you did" })
+\`\`\`
+Call this LAST before finishing. Catches missing .purpose files, missing gates, and compliance gaps.
+
+## Task-Size Compliance Guide
+
+Not every task needs the full ceremony. Match your effort to the scope:
+
+### Single-file bug fix (1 file changed)
+1. Session bookends (start + end)
+2. That's it \u2014 fix the bug, run postflight
+
+### Multi-file fix (2-3 files changed)
+1. Session bookends
+2. \`paradigm_ripple({ symbol: "#affected-symbol" })\` before changing
+3. Update nearest \`.purpose\` file if behavior changed
+4. Postflight
+
+### Feature build (3+ files, new behavior)
+1. Session bookends
+2. \`paradigm_pm_preflight({ task: "description" })\` \u2014 get compliance plan
+3. \`paradigm_ripple\` for each symbol you'll modify
+4. Implement the feature
+5. Create/update \`.purpose\` files for new directories
+6. Update \`portal.yaml\` if adding protected routes
+7. \`paradigm_pm_postflight\` \u2014 verify compliance
+8. \`paradigm_lore_record\` \u2014 record what you learned
+
+## The One Non-Negotiable Rule
+
+**You MUST update the nearest \`.purpose\` file when you change behavior.**
+
+- Adding a feature? Create a \`.purpose\` in the feature directory.
+- Modifying a component? Update its \`.purpose\` description, gates, or signals.
+- Deleting code? Remove the symbol from \`.purpose\`.
+- Not sure? Run \`paradigm_pm_postflight\` \u2014 it will tell you what's missing.
+
+## Essential MCP Tools (Use These, NOT CLI Commands)
+
+| Tool | When | Cost |
+|------|------|------|
+| \`paradigm_session_recover\` | Session start | ~100 tokens |
+| \`paradigm_ripple\` | Before modifying any symbol | ~300 tokens |
+| \`paradigm_navigate\` | Finding code locations | ~200 tokens |
+| \`paradigm_pm_preflight\` | Before starting a feature (3+ files) | ~200 tokens |
+| \`paradigm_pm_postflight\` | After finishing any task | ~200 tokens |
+| \`paradigm_reindex\` | After creating/modifying .purpose files | ~100 tokens |
+| \`paradigm_gates_for_route\` | Before adding API endpoints | ~150 tokens |
+| \`paradigm_lore_record\` | After completing a feature (record learnings) | ~100 tokens |
+
+## Red Flags \u2014 STOP and Check
+
+If you find yourself doing any of these, STOP:
+
+- **Modifying 3+ files without calling \`paradigm_ripple\`** \u2192 Check impact first
+- **Adding routes without checking \`paradigm_gates_for_route\`** \u2192 Get gate suggestions
+- **Finishing without running \`paradigm_pm_postflight\`** \u2192 You'll miss compliance gaps
+- **Creating directories without a \`.purpose\` file** \u2192 Every directory needs context
+`;
+  }
+  /**
+   * Practices - habits compliance, lore recording, llms.txt (Phase 5/6 content)
+   */
+  generatePracticesMdc() {
+    return frontmatter("Paradigm practices - habits, lore recording, and llms.txt. Apply when finishing tasks, recording history, or checking compliance.", {
+      alwaysApply: false
+    }) + `# Paradigm Practices
+
+` + generateHabitsSection() + "\n\n" + generateLoreSection() + "\n\n" + generateLlmsTxtSection();
   }
   /**
    * Load agents manifest from .paradigm/agents.yaml
@@ -2033,6 +2213,10 @@ var AgentsAdapter = class {
     sections.push(generateWorkflowProtocol());
     sections.push(generateCommitConvention());
     sections.push(generateHandoffProtocol());
+    sections.push(generateCheckpointProtocol());
+    sections.push(generateHabitsSection());
+    sections.push(generateLoreSection());
+    sections.push(generateLlmsTxtSection());
     const updateSection = generateUpdateRules(config);
     if (updateSection) {
       sections.push(updateSection);

package/dist/{chunk-UM54F7G5.js → chunk-4N6AYEEA.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   BackgroundOrchestrator
-} from "./chunk-AD2LSCHB.js";
+} from "./chunk-Y4XZWCHK.js";
 import {
   AGENT_MODEL_RECOMMENDATIONS,
   addActivity,

package/dist/{chunk-MVXJVRFI.js → chunk-5TUAVVIG.js}

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import {
+  __require
+} from "./chunk-MO4EEYFW.js";
 
 // src/core/lore/storage.ts
 import * as fs from "fs";
@@ -59,7 +62,67 @@ function applyLoreFilter(entries, filter) {
 var LORE_DIR = ".paradigm/lore";
 var ENTRIES_DIR = "entries";
 var TIMELINE_FILE = "timeline.yaml";
-async function recordLore(rootDir, entry) {
+function validateLoreSymbols(rootDir, symbols) {
+  const result = { unregistered: [], warnings: [] };
+  if (symbols.length === 0) return result;
+  const declaredSymbols = /* @__PURE__ */ new Set();
+  try {
+    const findResult = __require("child_process").execSync(
+      `find "${rootDir}" -name ".purpose" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null || true`,
+      { encoding: "utf-8" }
+    );
+    for (const purposePath of findResult.split("\n").filter(Boolean)) {
+      try {
+        const content = fs.readFileSync(purposePath, "utf8");
+        const symbolMatches = content.matchAll(/^([#$^!~][\w-]+):/gm);
+        for (const match of symbolMatches) {
+          declaredSymbols.add(match[1]);
+        }
+      } catch {
+      }
+    }
+  } catch {
+    return result;
+  }
+  const flowsPath = path.join(rootDir, ".paradigm", "flows.yaml");
+  if (fs.existsSync(flowsPath)) {
+    try {
+      const content = fs.readFileSync(flowsPath, "utf8");
+      const symbolMatches = content.matchAll(/([#$^!~][\w-]+)/g);
+      for (const match of symbolMatches) {
+        declaredSymbols.add(match[1]);
+      }
+    } catch {
+    }
+  }
+  const portalPath = path.join(rootDir, "portal.yaml");
+  if (fs.existsSync(portalPath)) {
+    try {
+      const content = fs.readFileSync(portalPath, "utf8");
+      const gateMatches = content.matchAll(/\^([\w-]+)/g);
+      for (const match of gateMatches) {
+        declaredSymbols.add(`^${match[1]}`);
+      }
+    } catch {
+    }
+  }
+  for (const symbol of symbols) {
+    if (!declaredSymbols.has(symbol)) {
+      result.unregistered.push(symbol);
+      result.warnings.push(`Symbol "${symbol}" not found in .purpose files or project index`);
+    }
+  }
+  return result;
+}
+async function recordLore(rootDir, entry, options) {
+  let validation;
+  if (options?.validateSymbols) {
+    const allSymbols = [
+      ...entry.symbols_touched || [],
+      ...entry.symbols_created || []
+    ];
+    validation = validateLoreSymbols(rootDir, allSymbols);
+  }
   const lorePath = path.join(rootDir, LORE_DIR);
   const dateStr = entry.timestamp.slice(0, 10);
   const datePath = path.join(lorePath, ENTRIES_DIR, dateStr);
@@ -72,6 +135,7 @@ async function recordLore(rootDir, entry) {
   const entryPath = path.join(datePath, `${entry.id}.yaml`);
   fs.writeFileSync(entryPath, yaml.dump(entry, { lineWidth: -1, noRefs: true }));
   await rebuildTimeline(rootDir);
+  return { validation };
 }
 async function loadLoreEntries(rootDir, filter) {
   const entriesPath = path.join(rootDir, LORE_DIR, ENTRIES_DIR);

package/dist/{chunk-5C4SGQKH.js → chunk-6P4IFIK2.js}

@@ -9,7 +9,7 @@ import {
   extractStates,
   extractSymbolReferences,
   getAllPurposeFiles
-} from "./chunk-PW2EXJQT.js";
+} from "./chunk-MRENOFTR.js";
 import {
   findGateFiles,
   parseGateConfig
@@ -330,7 +330,9 @@ async function aggregateFromPremise(premiseFile, rootDir) {
             data: item,
             description: item.description,
             anchors: item.anchors?.map((a) => parseAnchorString(a)),
-            appliesTo: item["applies-to"]
+            appliesTo: item["applies-to"],
+            tags: item.tags,
+            enforcement: item.enforcement
           }));
         }
         const symbolRefs = extractSymbolReferences(parsed);

package/dist/{chunk-WS5KM7OL.js → chunk-6RNYVBSG.js}

@@ -5,7 +5,7 @@ import {
 import {
   getProvider,
   initializeProviders
-} from "./chunk-TAP5N3HH.js";
+} from "./chunk-CCG6KYBT.js";
 import {
   loadAgentsManifest
 } from "./chunk-PMXRGPRQ.js";