@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/alkimia/context/context-tracker.js

@@ -0,0 +1,209 @@
+/**
+ * ALKIMIA Context Bracket Tracker
+ *
+ * Calculates the current context bracket (FRESH/MODERATE/DEPLETED/CRITICAL)
+ * based on estimated token usage. Provides token budgets and layer filtering
+ * per bracket for the AlkimiaEngine orchestrator.
+ *
+ * v2.22.0: Model-aware context tracking — budgets scale proportionally
+ * to the active model's context window (Opus 1M, Sonnet/Haiku 200K).
+ *
+ * v3.0.0: Part of V3 Claude Code ↔ Merlin alignment release.
+ *
+ * Pure arithmetic module -- zero I/O, zero external dependencies.
+ *
+ * @module core/alkimia/context/context-tracker
+ * @version 3.0.0
+ */
+
+/**
+ * Context window sizes per model tier.
+ * Source: Anthropic model documentation (March 2026)
+ *
+ * @constant
+ */
+const MODEL_CONTEXT_WINDOWS = {
+  opus: 1000000, // Claude Opus 4.6 — 1M tokens
+  sonnet: 200000, // Claude Sonnet 4.6 — 200K tokens
+  haiku: 200000, // Claude Haiku 4.5 — 200K tokens
+};
+
+/**
+ * Bracket definitions with thresholds and base token budgets.
+ * Base budgets are calibrated for Opus (1M context).
+ * For other models, use getTokenBudget(bracket, model) which scales proportionally.
+ *
+ * FRESH: 60-100% remaining (skills + essentials)
+ * MODERATE: 40-60% remaining (standard injection)
+ * DEPLETED: 25-40% remaining (reinforcement injection)
+ * CRITICAL: 0-25% remaining (warning + handoff prep)
+ */
+const BRACKETS = {
+  FRESH: { min: 60, max: 100, tokenBudget: 6000 },
+  MODERATE: { min: 40, max: 60, tokenBudget: 9000 },
+  DEPLETED: { min: 25, max: 40, tokenBudget: 12000 },
+  CRITICAL: { min: 0, max: 25, tokenBudget: 15000 },
+};
+
+/**
+ * Base token budgets per bracket (calibrated for Opus 1M context).
+ * For model-scaled budgets, use getTokenBudget(bracket, model).
+ *
+ * @constant
+ */
+const BASE_TOKEN_BUDGETS = {
+  FRESH: 6000,
+  MODERATE: 9000,
+  DEPLETED: 12000,
+  CRITICAL: 15000,
+};
+
+/**
+ * @deprecated Use BASE_TOKEN_BUDGETS + getTokenBudget(bracket, model) instead.
+ * Kept for backward compatibility with code that reads TOKEN_BUDGETS directly.
+ */
+const TOKEN_BUDGETS = BASE_TOKEN_BUDGETS;
+
+/**
+ * Minimum token budget floor.
+ * Ensures skills can still load even on the smallest context windows.
+ * @constant
+ */
+const MIN_TOKEN_BUDGET = 2000;
+
+const DEFAULTS = {
+  avgTokensPerPrompt: 1500,
+  maxContext: 1000000, // Fallback when model is not specified (Opus default)
+};
+
+/**
+ * Layer configurations per bracket.
+ *
+ * FRESH: L0 (Constitution), L1 (Global), L2 (Agent), L6 (Skill), L7 (Star-Command)
+ * MODERATE: All 8 layers active
+ * DEPLETED: All layers + memory hints enabled
+ * CRITICAL: All layers + memory hints + handoff warning
+ *
+ * v2.22.0: L6 now loads in FRESH bracket. With model-proportional budgets,
+ * skill injection is safe from the first prompt (0.6-1.7% of remaining context).
+ */
+const LAYER_CONFIGS = {
+  FRESH: { layers: [0, 1, 2, 6, 7], memoryHints: false, handoffWarning: false },
+  MODERATE: {
+    layers: [0, 1, 2, 3, 4, 5, 6, 7],
+    memoryHints: false,
+    handoffWarning: false,
+  },
+  DEPLETED: {
+    layers: [0, 1, 2, 3, 4, 5, 6, 7],
+    memoryHints: true,
+    handoffWarning: false,
+  },
+  CRITICAL: {
+    layers: [0, 1, 2, 3, 4, 5, 6, 7],
+    memoryHints: true,
+    handoffWarning: true,
+  },
+};
+
+/**
+ * Calculate the context bracket based on remaining context percentage.
+ *
+ * @param {number} contextPercent - Percentage of context remaining (0-100)
+ * @returns {string} Bracket name: 'FRESH' | 'MODERATE' | 'DEPLETED' | 'CRITICAL'
+ */
+function calculateBracket(contextPercent) {
+  if (typeof contextPercent !== "number" || isNaN(contextPercent))
+    return "CRITICAL";
+  if (contextPercent >= 60) return "FRESH";
+  if (contextPercent >= 40) return "MODERATE";
+  if (contextPercent >= 25) return "DEPLETED";
+  return "CRITICAL";
+}
+
+/**
+ * Estimate the percentage of context remaining based on prompt count.
+ *
+ * v2.22.0: Accepts optional `model` parameter to use model-specific context window.
+ * Without model, falls back to maxContext (1M default) for backward compatibility.
+ *
+ * @param {number} promptCount - Number of prompts in current session
+ * @param {Object} [options={}] - Configuration options
+ * @param {number} [options.avgTokensPerPrompt=1500] - Average tokens per prompt
+ * @param {number} [options.maxContext=1000000] - Fallback max context (used only when model is not provided or unknown)
+ * @param {string} [options.model] - Model tier (opus/sonnet/haiku). When valid, takes precedence over maxContext.
+ * @returns {number} Percentage of context remaining (0.0 to 100.0)
+ */
+function estimateContextPercent(promptCount, options = {}) {
+  const {
+    avgTokensPerPrompt = DEFAULTS.avgTokensPerPrompt,
+    maxContext = DEFAULTS.maxContext,
+    model = null,
+  } = options;
+
+  // Use model-specific context window if model is provided
+  const effectiveMaxContext =
+    model && MODEL_CONTEXT_WINDOWS[model]
+      ? MODEL_CONTEXT_WINDOWS[model]
+      : maxContext;
+
+  if (typeof promptCount !== "number" || isNaN(promptCount) || promptCount < 0)
+    return 100;
+  if (effectiveMaxContext <= 0) return 0;
+
+  const usedTokens = promptCount * avgTokensPerPrompt;
+  const percent = 100 - (usedTokens / effectiveMaxContext) * 100;
+  return Math.max(0, Math.min(100, percent));
+}
+
+/**
+ * Get the token budget for a bracket, optionally scaled to a model's context window.
+ *
+ * Base budgets are calibrated for Opus (1M). For smaller models (Sonnet/Haiku at 200K),
+ * the budget scales proportionally: 200K/1M = 0.2x, with a floor of MIN_TOKEN_BUDGET.
+ *
+ * @param {string} bracket - Context bracket (FRESH/MODERATE/DEPLETED/CRITICAL)
+ * @param {string} [model] - Model tier (opus/sonnet/haiku). Without model, returns base (Opus) budget.
+ * @returns {number|null} Token budget, or null for unknown bracket
+ */
+function getTokenBudget(bracket, model) {
+  const base = BASE_TOKEN_BUDGETS[bracket];
+  if (base === undefined) return null;
+  if (!model || !MODEL_CONTEXT_WINDOWS[model]) return base;
+
+  const scale = MODEL_CONTEXT_WINDOWS[model] / 1000000;
+  return Math.max(MIN_TOKEN_BUDGET, Math.round(base * scale));
+}
+
+function getActiveLayers(bracket) {
+  const config = LAYER_CONFIGS[bracket];
+  if (!config) return null;
+  return {
+    layers: [...config.layers],
+    memoryHints: config.memoryHints,
+    handoffWarning: config.handoffWarning,
+  };
+}
+
+function needsHandoffWarning(bracket) {
+  return bracket === "CRITICAL";
+}
+
+function needsMemoryHints(bracket) {
+  return bracket === "DEPLETED" || bracket === "CRITICAL";
+}
+
+module.exports = {
+  calculateBracket,
+  estimateContextPercent,
+  getTokenBudget,
+  getActiveLayers,
+  needsHandoffWarning,
+  needsMemoryHints,
+  BRACKETS,
+  TOKEN_BUDGETS,
+  BASE_TOKEN_BUDGETS,
+  MODEL_CONTEXT_WINDOWS,
+  MIN_TOKEN_BUDGET,
+  DEFAULTS,
+};

package/.merlin-core/core/alkimia/domain/domain-loader.js

@@ -0,0 +1,215 @@
+/**
+ * Domain Loader + Manifest Parser
+ *
+ * Loads and parses the .alkimia/manifest (KEY=VALUE format)
+ * and individual domain files. Provides the data foundation for all 8 ALKIMIA layers.
+ *
+ * @module core/alkimia/domain/domain-loader
+ * @version 3.0.0
+ */
+
+const fs = require("fs");
+
+/**
+ * Known domain attribute suffixes (order matters -- longest first)
+ */
+const KNOWN_SUFFIXES = [
+  "_WORKFLOW_TRIGGER",
+  "_AGENT_TRIGGER",
+  "_NON_NEGOTIABLE",
+  "_ALWAYS_ON",
+  "_EXCLUDE",
+  "_RECALL",
+  "_STATE",
+];
+
+/**
+ * Global-level keys that are NOT domain attributes
+ */
+const GLOBAL_KEYS = ["DEVMODE", "GLOBAL_EXCLUDE"];
+
+/**
+ * Parse the .alkimia/manifest file (KEY=VALUE format)
+ *
+ * @param {string} manifestPath - Absolute path to manifest file
+ * @returns {object} Parsed manifest with domains, devmode, and globalExclude
+ */
+function parseManifest(manifestPath) {
+  let content;
+  try {
+    content = fs.readFileSync(manifestPath, "utf8");
+  } catch {
+    return { devmode: false, globalExclude: [], domains: {} };
+  }
+
+  const result = { devmode: false, globalExclude: [], domains: {} };
+  const lines = content.split(/\r?\n/);
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+
+    const key = trimmed.substring(0, eqIndex).trim();
+    const value = trimmed.substring(eqIndex + 1).trim();
+    if (!key) continue;
+
+    if (key === "DEVMODE") {
+      result.devmode = value.toLowerCase() === "true";
+      continue;
+    }
+    if (key === "GLOBAL_EXCLUDE") {
+      result.globalExclude = parseCommaSeparated(value);
+      continue;
+    }
+
+    const { domainName, suffix } = extractDomainInfo(key);
+    if (!domainName) continue;
+
+    if (!result.domains[domainName]) {
+      result.domains[domainName] = { file: domainNameToFile(domainName) };
+    }
+
+    const domain = result.domains[domainName];
+    switch (suffix) {
+      case "_STATE":
+        domain.state = value.toLowerCase();
+        break;
+      case "_ALWAYS_ON":
+        domain.alwaysOn = value.toLowerCase() === "true";
+        break;
+      case "_NON_NEGOTIABLE":
+        domain.nonNegotiable = value.toLowerCase() === "true";
+        break;
+      case "_AGENT_TRIGGER":
+        domain.agentTrigger = value;
+        break;
+      case "_WORKFLOW_TRIGGER":
+        domain.workflowTrigger = value;
+        break;
+      case "_RECALL":
+        domain.recall = parseCommaSeparated(value);
+        break;
+      case "_EXCLUDE":
+        domain.exclude = parseCommaSeparated(value);
+        break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load a domain file and extract rules
+ *
+ * @param {string} domainPath - Absolute path to domain file
+ * @returns {string[]} Array of rule strings (empty array if file missing)
+ */
+function loadDomainFile(domainPath) {
+  let content;
+  try {
+    content = fs.readFileSync(domainPath, "utf8");
+  } catch {
+    return [];
+  }
+
+  const lines = content.split(/\r?\n/);
+  const rules = [];
+  let hasKeyValueFormat = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (
+      trimmed &&
+      !trimmed.startsWith("#") &&
+      /^[A-Z][A-Z0-9_]*=/.test(trimmed)
+    ) {
+      hasKeyValueFormat = true;
+      break;
+    }
+  }
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    if (hasKeyValueFormat) {
+      const match = trimmed.match(/^[A-Z][A-Z0-9_]*=(.+)$/);
+      if (match) rules.push(match[1].trim());
+    } else {
+      rules.push(trimmed);
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Check if a prompt should be excluded based on exclusion keywords
+ */
+function isExcluded(prompt, globalExcludes = [], domainExcludes = []) {
+  if (!prompt) return false;
+  const promptLower = prompt.toLowerCase();
+  const allExcludes = [...globalExcludes, ...domainExcludes];
+
+  for (const keyword of allExcludes) {
+    if (!keyword) continue;
+    const escaped = keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (new RegExp(escaped, "i").test(promptLower)) return true;
+  }
+  return false;
+}
+
+/**
+ * Check if a prompt matches any recall keywords
+ */
+function matchKeywords(prompt, recallKeywords = []) {
+  if (!prompt || recallKeywords.length === 0) return false;
+  const promptLower = prompt.toLowerCase();
+
+  for (const keyword of recallKeywords) {
+    if (!keyword) continue;
+    // Escape first, then normalize hyphens (order matters — [-\s] must not be escaped)
+    const escaped = keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // Normalize: hyphens match spaces too (slide-deck = slide deck)
+    const normalized = escaped.replace(/-/g, "[-\\s]");
+    // Word-boundary matching: "code" matches "write code" but NOT "encode"
+    if (new RegExp(`\\b${normalized}\\b`, "i").test(promptLower)) return true;
+  }
+  return false;
+}
+
+function extractDomainInfo(key) {
+  for (const suffix of KNOWN_SUFFIXES) {
+    if (key.endsWith(suffix)) {
+      const domainName = key.substring(0, key.length - suffix.length);
+      if (domainName) return { domainName, suffix };
+    }
+  }
+  return { domainName: null, suffix: null };
+}
+
+function domainNameToFile(domainName) {
+  return domainName.toLowerCase().replace(/_/g, "-");
+}
+
+function parseCommaSeparated(value) {
+  if (!value) return [];
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+module.exports = {
+  parseManifest,
+  loadDomainFile,
+  isExcluded,
+  matchKeywords,
+  extractDomainInfo,
+  domainNameToFile,
+  KNOWN_SUFFIXES,
+  GLOBAL_KEYS,
+};

package/.merlin-core/core/alkimia/engine.js

@@ -0,0 +1,284 @@
+/**
+ * AlkimiaEngine -- Orchestrator for the 8-layer context injection pipeline.
+ *
+ * Merlin's Alkimia engine executes L0-L7 sequentially, applies bracket-aware
+ * filtering via context-tracker, collects pipeline metrics, and formats
+ * the final <alkimia-rules> XML output.
+ *
+ * L6 uses composable skill modules (from .merlin-core/skills/)
+ * for rich domain knowledge injection into the pipeline.
+ *
+ * @module core/alkimia/engine
+ * @version 3.0.0
+ */
+
+const path = require("path");
+
+const {
+  estimateContextPercent,
+  calculateBracket,
+  getActiveLayers,
+  getTokenBudget,
+  needsMemoryHints,
+  needsHandoffWarning,
+} = require("./context/context-tracker");
+
+const { formatAlkimiaRules } = require("./output/formatter");
+const { MemoryBridge } = require("./memory/memory-bridge");
+const { ThoughtsProvider } = require("./memory/thoughts-provider");
+
+// ---------------------------------------------------------------------------
+// Layer Imports (graceful -- layers may not exist yet)
+// ---------------------------------------------------------------------------
+
+const LAYER_MODULES = [
+  { path: "./layers/l0-constitution", layer: 0, name: "constitution" },
+  { path: "./layers/l1-global", layer: 1, name: "global" },
+  { path: "./layers/l2-agent", layer: 2, name: "agent" },
+  { path: "./layers/l3-workflow", layer: 3, name: "workflow" },
+  { path: "./layers/l4-task", layer: 4, name: "task" },
+  { path: "./layers/l5-squad", layer: 5, name: "squad" },
+  { path: "./layers/l6-skill", layer: 6, name: "skill" },
+  { path: "./layers/l7-star-command", layer: 7, name: "star-command" },
+];
+
+function loadLayerModule(modulePath) {
+  try {
+    return require(modulePath);
+  } catch (err) {
+    if (
+      err.code === "MODULE_NOT_FOUND" &&
+      err.message &&
+      err.message.includes(modulePath)
+    ) {
+      return null;
+    }
+    console.warn(
+      `[alkimia:engine] Unexpected error loading ${modulePath}: ${err.message}`,
+    );
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// PipelineMetrics
+// ---------------------------------------------------------------------------
+
+class PipelineMetrics {
+  constructor() {
+    this.layers = {};
+    this.totalStart = null;
+    this.totalEnd = null;
+  }
+
+  startLayer(name) {
+    this.layers[name] = { start: Date.now(), status: "running" };
+  }
+
+  endLayer(name, rulesCount) {
+    const layer = this.layers[name];
+    if (!layer) {
+      this.layers[name] = { status: "ok", rules: rulesCount };
+      return;
+    }
+    layer.end = Date.now();
+    layer.duration = layer.end - layer.start;
+    layer.status = "ok";
+    layer.rules = rulesCount;
+  }
+
+  skipLayer(name, reason) {
+    this.layers[name] = { status: "skipped", reason };
+  }
+
+  errorLayer(name, error) {
+    const existing = this.layers[name] || {};
+    if (existing.start) {
+      existing.end = Date.now();
+      existing.duration = existing.end - existing.start;
+    }
+    this.layers[name] = {
+      ...existing,
+      status: "error",
+      error: error && error.message ? error.message : String(error),
+    };
+  }
+
+  getSummary() {
+    const values = Object.values(this.layers);
+    return {
+      total_ms:
+        this.totalStart != null && this.totalEnd != null
+          ? this.totalEnd - this.totalStart
+          : 0,
+      layers_loaded: values.filter((l) => l.status === "ok").length,
+      layers_skipped: values.filter((l) => l.status === "skipped").length,
+      layers_errored: values.filter((l) => l.status === "error").length,
+      total_rules: values.reduce((sum, l) => sum + (l.rules || 0), 0),
+      per_layer: this.layers,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// AlkimiaEngine
+// ---------------------------------------------------------------------------
+
+const PIPELINE_TIMEOUT_MS = 100;
+
+/**
+ * Orchestrates the 8-layer ALKIMIA context injection pipeline.
+ *
+ * Layers:
+ *   L0 - Constitution (7 Merlin principles)
+ *   L1 - Global (universal rules)
+ *   L2 - Agent (active agent rules)
+ *   L3 - Workflow (active workflow + Folloni phase)
+ *   L4 - Task (active task context)
+ *   L5 - Squad (squad domain rules)
+ *   L6 - Skill (composable knowledge modules) -- NEW
+ *   L7 - Star-Command (explicit *command overrides)
+ */
+class AlkimiaEngine {
+  constructor(alkimiaPath, config = {}) {
+    this.alkimiaPath = alkimiaPath;
+    this.config = config;
+    this.layers = [];
+    this.memoryBridge = new MemoryBridge({ timeout: 50 });
+
+    // Register Thoughts Provider for bracket-aware knowledge retrieval (Wave 1)
+    try {
+      const thoughtsPath = path.join(
+        path.dirname(alkimiaPath),
+        "..",
+        "thoughts",
+      );
+      this.memoryBridge.registerProvider(new ThoughtsProvider(thoughtsPath));
+    } catch (err) {
+      console.warn(
+        `[alkimia:engine] ThoughtsProvider init failed: ${err.message}`,
+      );
+    }
+
+    for (const mod of LAYER_MODULES) {
+      const LayerClass = loadLayerModule(mod.path);
+      if (LayerClass) {
+        try {
+          this.layers.push(new LayerClass());
+        } catch (err) {
+          console.warn(
+            `[alkimia:engine] Failed to instantiate layer ${mod.name}: ${err.message}`,
+          );
+        }
+      }
+    }
+  }
+
+  async process(prompt, session, processConfig) {
+    const safeProcessConfig =
+      processConfig && typeof processConfig === "object" ? processConfig : {};
+    const mergedConfig = { ...this.config, ...safeProcessConfig };
+    const metrics = new PipelineMetrics();
+    metrics.totalStart = Date.now();
+
+    // 1. Calculate bracket (model-aware since v2.22.0)
+    const promptCount = (session && session.prompt_count) || 0;
+    const activeModel = (session && session.active_model) || null;
+    const contextPercent = estimateContextPercent(promptCount, {
+      model: activeModel,
+    });
+    const bracket = calculateBracket(contextPercent);
+    const layerConfig = getActiveLayers(bracket);
+    const tokenBudget = getTokenBudget(bracket, activeModel);
+
+    if (!layerConfig) {
+      metrics.totalEnd = Date.now();
+      return { xml: "", metrics: metrics.getSummary() };
+    }
+
+    const activeLayers = layerConfig.layers;
+    const results = [];
+    const previousLayers = [];
+
+    // 2. Execute layers sequentially
+    for (const layer of this.layers) {
+      if (!activeLayers.includes(layer.layer)) {
+        metrics.skipLayer(layer.name, `Not active in ${bracket}`);
+        continue;
+      }
+
+      if (Date.now() - metrics.totalStart > PIPELINE_TIMEOUT_MS) {
+        const remaining = this.layers.slice(this.layers.indexOf(layer));
+        for (const r of remaining) {
+          if (activeLayers.includes(r.layer) && !metrics.layers[r.name]) {
+            metrics.skipLayer(r.name, "Pipeline timeout");
+          }
+        }
+        break;
+      }
+
+      metrics.startLayer(layer.name);
+      const context = {
+        prompt,
+        session: session || {},
+        config: {
+          ...mergedConfig,
+          alkimiaPath: this.alkimiaPath,
+          manifest: mergedConfig.manifest || {},
+        },
+        previousLayers,
+      };
+
+      const result = layer._safeProcess(context);
+
+      if (result && Array.isArray(result.rules)) {
+        metrics.endLayer(layer.name, result.rules.length);
+        results.push(result);
+        previousLayers.push(result);
+      } else if (result === null || result === undefined) {
+        metrics.skipLayer(layer.name, "Returned null");
+      } else {
+        metrics.skipLayer(layer.name, "Invalid result format");
+      }
+    }
+
+    // 3. Memory bridge
+    if (needsMemoryHints(bracket)) {
+      const hints = await this.memoryBridge.getMemoryHints(
+        (session && session.activeAgent) ||
+          (session && session.active_agent) ||
+          "",
+        bracket,
+        tokenBudget,
+      );
+      if (hints.length > 0) {
+        const memoryResult = {
+          layer: "memory",
+          rules: hints,
+          metadata: { layer: "memory", source: "memory" },
+        };
+        results.push(memoryResult);
+        previousLayers.push(memoryResult);
+      }
+    }
+
+    metrics.totalEnd = Date.now();
+    const summary = metrics.getSummary();
+
+    // 4. Format output
+    const xml = formatAlkimiaRules(
+      results,
+      bracket,
+      contextPercent,
+      session || {},
+      mergedConfig.devmode === true,
+      summary,
+      tokenBudget,
+      needsHandoffWarning(bracket),
+    );
+
+    return { xml, metrics: summary };
+  }
+}
+
+module.exports = { AlkimiaEngine, PipelineMetrics, PIPELINE_TIMEOUT_MS };