@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/orchestration/session-state.js

@@ -0,0 +1,430 @@
+/**
+ * Session State -- Persistence for crash recovery and resume
+ *
+ * Persists session state to disk so that work can be resumed after
+ * crashes, pauses, or between sessions. State is stored in
+ * .merlin/session-state.json (gitignored runtime directory).
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/orchestration/session-state
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs").promises;
+const path = require("path");
+
+/**
+ * Session state file name
+ * @constant {string}
+ */
+const SESSION_STATE_FILE = "session-state.json";
+
+/**
+ * Message types for Notify vs Ask protocol.
+ * Agents use these to distinguish blocking questions from status updates.
+ * @enum {string}
+ */
+const MessageType = {
+  NOTIFY: "notify", // Non-blocking status update — orchestrator logs it
+  ASK: "ask", // Blocking question — requires user/orchestrator response
+  PROGRESS: "progress", // Incremental progress update — emitted during long tasks
+  RESULT: "result", // Final result — signals dispatch completion
+  THOUGHT: "thought", // Internal reasoning — stored in logs, NOT shown to user
+};
+
+/**
+ * Action types for session state tracking
+ * @enum {string}
+ */
+const ActionType = {
+  GO: "GO",
+  PAUSE: "PAUSE",
+  REVIEW: "REVIEW",
+  ABORT: "ABORT",
+  PHASE_CHANGE: "PHASE_CHANGE",
+  TASK_STARTED: "TASK_STARTED",
+  TASK_COMPLETED: "TASK_COMPLETED",
+  ERROR_OCCURRED: "ERROR_OCCURRED",
+  REFLECT_CHECKPOINT: "REFLECT_CHECKPOINT",
+};
+
+/**
+ * Development cycle phase names
+ * @enum {string}
+ */
+const Phase = {
+  RESEARCH: "research",
+  ARCHITECTURE: "architecture",
+  IMPLEMENTATION: "implementation",
+  REVIEW: "review",
+  DEPLOYMENT: "deployment",
+};
+
+/**
+ * SessionState -- Manages session persistence for the orchestration engine.
+ */
+class SessionState {
+  /**
+   * @param {string} projectRoot - Project root directory
+   * @param {Object} [options] - Options
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(projectRoot, options = {}) {
+    this.projectRoot = projectRoot;
+    this.options = { debug: false, ...options };
+
+    this.stateFilePath = path.join(projectRoot, ".merlin", SESSION_STATE_FILE);
+    this.state = null;
+  }
+
+  /**
+   * Check if a session state file exists.
+   * @returns {Promise<boolean>}
+   */
+  async exists() {
+    try {
+      await fs.access(this.stateFilePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Load session state from disk.
+   * @returns {Promise<Object|null>} Session state or null
+   */
+  async load() {
+    try {
+      if (!(await this.exists())) return null;
+
+      const content = await fs.readFile(this.stateFilePath, "utf8");
+
+      // Simple YAML-like deserialization (key: value format)
+      // For a production system, use js-yaml.
+      // Here we store as JSON for reliability with native modules.
+      this.state = JSON.parse(content);
+
+      this._log(`Session state loaded from ${this.stateFilePath}`);
+      return this.state;
+    } catch (error) {
+      this._log(`Failed to load session state: ${error.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Save session state to disk.
+   * @returns {Promise<void>}
+   */
+  async save() {
+    if (!this.state) {
+      throw new Error("No state to save. Call load() or create state first.");
+    }
+
+    // Update timestamp
+    this.state.lastUpdated = new Date().toISOString();
+
+    // Ensure directory exists
+    const dir = path.dirname(this.stateFilePath);
+    await fs.mkdir(dir, { recursive: true });
+
+    // Write state (using JSON for native-module compatibility)
+    await fs.writeFile(
+      this.stateFilePath,
+      JSON.stringify(this.state, null, 2),
+      "utf8",
+    );
+
+    this._log("Session state saved");
+  }
+
+  /**
+   * Create a new session state.
+   *
+   * @param {Object} initialData - Initial state data
+   * @param {string} [initialData.workflowId] - Active workflow
+   * @param {string} [initialData.currentPhase] - Current phase
+   * @param {string} [initialData.currentTask] - Current task
+   * @returns {Promise<Object>} Created state
+   */
+  async create(initialData = {}) {
+    const now = new Date().toISOString();
+
+    this.state = {
+      version: "1.1",
+      createdAt: now,
+      lastUpdated: now,
+      workflowId: initialData.workflowId || null,
+      currentPhase: initialData.currentPhase || null,
+      currentTask: initialData.currentTask || null,
+      phaseResults: {},
+      actionLog: [],
+      context: {},
+      reminders: [], // Active reminders from thoughts/shared/reminders/ (Constitution VIII)
+      objectives: [], // Active objectives from thoughts/shared/objectives/ (Constitution VIII)
+      processes: [], // Certified processes from thoughts/shared/processes/ (Constitution XIV)
+    };
+
+    await this.save();
+    this._log("New session state created");
+    return this.state;
+  }
+
+  /**
+   * Record an action in the session log.
+   *
+   * @param {string} type - ActionType value
+   * @param {Object} [data={}] - Action-specific data
+   * @returns {Promise<void>}
+   */
+  async recordAction(type, data = {}) {
+    if (!this.state) {
+      (await this.load()) || (await this.create());
+    }
+
+    const entry = {
+      type,
+      timestamp: new Date().toISOString(),
+      ...data,
+    };
+
+    this.state.actionLog.push(entry);
+
+    // Update current phase/task if relevant
+    if (type === ActionType.PHASE_CHANGE && data.phase) {
+      this.state.currentPhase = data.phase;
+    }
+    if (type === ActionType.TASK_STARTED && data.task) {
+      this.state.currentTask = data.task;
+    }
+    if (type === ActionType.TASK_COMPLETED) {
+      this.state.currentTask = null;
+    }
+
+    await this.save();
+    this._log(`Action recorded: ${type}`);
+  }
+
+  /**
+   * Get a resume suggestion by examining current state.
+   *
+   * Analyzes the last action and current phase to recommend
+   * whether to continue, retry, or start fresh.
+   *
+   * @returns {Object} Resume suggestion with strategy and reason
+   */
+  getResumeSuggestion() {
+    if (!this.state) {
+      return { strategy: "fresh_start", reason: "No session state found" };
+    }
+
+    const lastAction = this.state.actionLog[this.state.actionLog.length - 1];
+
+    if (!lastAction) {
+      return { strategy: "fresh_start", reason: "Empty action log" };
+    }
+
+    // Check how long ago the last action was
+    const lastTime = new Date(lastAction.timestamp);
+    const minutesSince = (Date.now() - lastTime.getTime()) / (1000 * 60);
+
+    // If paused explicitly, suggest continue
+    if (lastAction.type === ActionType.PAUSE) {
+      return {
+        strategy: "continue",
+        reason: `Session was paused ${Math.round(minutesSince)} minutes ago`,
+        phase: this.state.currentPhase,
+        task: this.state.currentTask,
+      };
+    }
+
+    // If error occurred, suggest retry
+    if (lastAction.type === ActionType.ERROR_OCCURRED) {
+      return {
+        strategy: "retry",
+        reason: `Error occurred in phase "${this.state.currentPhase}": ${lastAction.error || "unknown"}`,
+        phase: this.state.currentPhase,
+      };
+    }
+
+    // If task was in progress and >30 min passed, likely a crash
+    if (lastAction.type === ActionType.TASK_STARTED && minutesSince > 30) {
+      return {
+        strategy: "retry",
+        reason: `Possible crash detected (${Math.round(minutesSince)} min since last activity)`,
+        phase: this.state.currentPhase,
+        task: this.state.currentTask,
+      };
+    }
+
+    // If recently active, suggest continue
+    if (minutesSince < 30) {
+      return {
+        strategy: "continue",
+        reason: "Session is recent and active",
+        phase: this.state.currentPhase,
+        task: this.state.currentTask,
+      };
+    }
+
+    // Default: suggest continue from last known state
+    return {
+      strategy: "continue",
+      reason: `Last activity ${Math.round(minutesSince)} minutes ago`,
+      phase: this.state.currentPhase,
+    };
+  }
+
+  /**
+   * Get active reminders (pending or acknowledged).
+   * @returns {Array} Active reminder objects
+   */
+  getActiveReminders() {
+    if (!this.state || !this.state.reminders) return [];
+    return this.state.reminders.filter(
+      (r) => r.status === "pending" || r.status === "acknowledged",
+    );
+  }
+
+  /**
+   * Get active objectives (status = active).
+   * @returns {Array} Active objective objects
+   */
+  getActiveObjectives() {
+    if (!this.state || !this.state.objectives) return [];
+    return this.state.objectives.filter((o) => o.status === "active");
+  }
+
+  /**
+   * Get certified processes (status = certified) — runnable autonomously (Constitution XIV).
+   * @returns {Array} Certified process objects
+   */
+  getActiveProcesses() {
+    if (!this.state || !this.state.processes) return [];
+    return this.state.processes.filter((p) => p.status === "certified");
+  }
+
+  /**
+   * Connect an EventBus instance for automatic event recording.
+   *
+   * Subscribes to workflow:*, agent:*, and agent-hook:* channels and
+   * auto-records events into the actionLog via recordAction().
+   *
+   * @param {Object} eventBus - EventBus instance
+   * @returns {Function[]} Array of unsubscribe functions
+   */
+  connectEventBus(eventBus) {
+    if (!eventBus || typeof eventBus.subscribe !== "function") {
+      throw new Error("connectEventBus requires a valid EventBus instance");
+    }
+
+    const EVENT_MAP = {
+      "phase-started": ActionType.PHASE_CHANGE,
+      "phase-completed": ActionType.PHASE_CHANGE,
+      spawned: ActionType.TASK_STARTED,
+      "dispatch-start": ActionType.TASK_STARTED,
+      "dispatch-end": ActionType.TASK_COMPLETED,
+      completed: ActionType.TASK_COMPLETED,
+      error: ActionType.ERROR_OCCURRED,
+      triggered: ActionType.GO,
+    };
+
+    const channels = ["workflow", "agent", "agent-hook"];
+    const unsubscribers = [];
+
+    for (const channel of channels) {
+      const unsub = eventBus.subscribe(channel, ({ event, data }) => {
+        const actionType = EVENT_MAP[event] || ActionType.GO;
+        this.recordAction(actionType, {
+          source: `${channel}:${event}`,
+          eventData: data,
+        }).catch((err) => {
+          this._log(`Event recording failed: ${err.message}`);
+        });
+      });
+      unsubscribers.push(unsub);
+    }
+
+    this._eventBusConnected = true;
+    return unsubscribers;
+  }
+
+  /**
+   * Get the action log as a typed, filterable event stream.
+   *
+   * @param {Object} [options]
+   * @param {string} [options.type] - Filter by ActionType value
+   * @param {string} [options.channel] - Filter by source channel prefix
+   * @param {string} [options.since] - ISO timestamp — only events after this time
+   * @param {number} [options.limit] - Maximum number of events to return
+   * @returns {Array<Object>} Filtered event stream
+   */
+  getEventStream(options = {}) {
+    if (!this.state || !this.state.actionLog) return [];
+
+    let stream = [...this.state.actionLog];
+
+    if (options.type) {
+      stream = stream.filter((e) => e.type === options.type);
+    }
+
+    if (options.channel) {
+      stream = stream.filter(
+        (e) => e.source && e.source.startsWith(options.channel),
+      );
+    }
+
+    if (options.since) {
+      const sinceTime = new Date(options.since).getTime();
+      stream = stream.filter(
+        (e) => new Date(e.timestamp).getTime() >= sinceTime,
+      );
+    }
+
+    if (options.limit && options.limit > 0) {
+      stream = stream.slice(-options.limit);
+    }
+
+    return stream;
+  }
+
+  /**
+   * Clear the session state (reset).
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    this.state = null;
+
+    try {
+      if (await this.exists()) {
+        await fs.unlink(this.stateFilePath);
+        this._log("Session state cleared");
+      }
+    } catch (error) {
+      this._log(`Failed to clear session state: ${error.message}`);
+    }
+  }
+
+  /**
+   * Debug logger.
+   * @param {string} message
+   * @private
+   */
+  _log(message) {
+    if (this.options.debug) {
+      console.log(`[SessionState] ${message}`);
+    }
+  }
+}
+
+module.exports = {
+  SessionState,
+  ActionType,
+  Phase,
+  MessageType,
+  SESSION_STATE_FILE,
+};

package/.merlin-core/core/orchestration/skill-dispatcher.js

@@ -0,0 +1,255 @@
+/**
+ * Skill Dispatcher -- Dispatches skill execution during orchestration
+ *
+ * Discovers and dispatches skills from the .merlin-core/skills/ directory.
+ * Skills are self-contained capability modules with SKILL.md definitions
+ * containing frontmatter metadata and instructions.
+ *
+ * Skill directories:
+ * - .merlin-core/skills/general/ -- universal skills
+ * - .merlin-core/skills/domain/  -- domain-specific skills
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/orchestration/skill-dispatcher
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const fsPromises = require("fs").promises;
+const path = require("path");
+const {
+  parseFrontmatter,
+  parseSkillFrontmatter,
+  parseYamlArray,
+  extractFrontmatter,
+} = require("../alkimia/utils/frontmatter");
+
+/**
+ * SkillDispatcher -- Discovers and dispatches skills.
+ */
+class SkillDispatcher {
+  /**
+   * @param {Object} [options] - Configuration options
+   * @param {string} [options.projectRoot] - Project root path
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.debug = options.debug ?? false;
+
+    // Skill directories (order = priority: first wins on dedup)
+    this.skillDirs = [
+      path.join(this.projectRoot, ".merlin-core", "skills", "general"),
+      path.join(this.projectRoot, ".merlin-core", "skills", "domain"),
+      path.join(this.projectRoot, ".agents", "skills"),
+    ];
+
+    // Cache of discovered skills
+    this._skillCache = null;
+  }
+
+  /**
+   * Dispatch a skill by its ID.
+   *
+   * Loads the skill definition and returns the activation context
+   * for the orchestrator to pass to the executing agent.
+   *
+   * @param {string} skillId - Skill identifier (directory name)
+   * @param {Object} [context={}] - Execution context
+   * @returns {Promise<Object>} Dispatch result with skill definition and context
+   */
+  async dispatch(skillId, context = {}) {
+    this._log(`Dispatching skill: ${skillId}`);
+
+    const skill = await this._loadSkill(skillId);
+    if (!skill) {
+      return {
+        success: false,
+        error: `Skill not found: ${skillId}`,
+      };
+    }
+
+    return {
+      success: true,
+      skillId,
+      name: skill.name,
+      description: skill.description,
+      content: skill.content,
+      metadata: skill.metadata,
+      context: {
+        ...context,
+        skillId,
+        activatedAt: new Date().toISOString(),
+      },
+    };
+  }
+
+  /**
+   * Load a skill definition by reading its SKILL.md file
+   * and parsing the frontmatter.
+   *
+   * @param {string} skillId - Skill identifier
+   * @returns {Promise<Object|null>} Skill definition or null
+   * @private
+   */
+  async _loadSkill(skillId) {
+    // Search all skill directories
+    for (const dir of this.skillDirs) {
+      const skillDir = path.join(dir, skillId);
+      const skillFile = path.join(skillDir, "SKILL.md");
+
+      if (fs.existsSync(skillFile)) {
+        try {
+          const rawContent = await fsPromises.readFile(skillFile, "utf8");
+          const metadata = this._parseFrontmatter(rawContent);
+
+          // N5 fix: strip frontmatter from content so consumers get clean instructions
+          const { body } = extractFrontmatter(rawContent);
+
+          return {
+            id: skillId,
+            name: metadata.name || skillId,
+            description: metadata.description || "",
+            keywords: metadata.keywords || [],
+            auto_activate: metadata.auto_activate || [],
+            content: body,
+            metadata,
+            path: skillDir,
+          };
+        } catch (error) {
+          this._log(`Failed to load skill ${skillId}: ${error.message}`);
+          return null;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * List all available skills by scanning skill directories.
+   *
+   * @returns {Promise<Object[]>} Array of skill summaries
+   */
+  async listAvailable() {
+    if (this._skillCache) return this._skillCache;
+
+    const skills = [];
+    const seenIds = new Set();
+
+    for (const dir of this.skillDirs) {
+      if (!fs.existsSync(dir)) continue;
+
+      // Determine category from relative path (avoids false positives from absolute path)
+      const relDir = path.relative(this.projectRoot, dir);
+      const category = relDir.includes("domain")
+        ? "domain"
+        : relDir.includes(".agents")
+          ? "agents"
+          : "general";
+
+      try {
+        const entries = await fsPromises.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue;
+          if (seenIds.has(entry.name)) continue; // dedup: first dir wins
+
+          const skillFile = path.join(dir, entry.name, "SKILL.md");
+          if (!fs.existsSync(skillFile)) continue;
+
+          try {
+            const content = await fsPromises.readFile(skillFile, "utf8");
+            const metadata = this._parseFrontmatter(content);
+
+            seenIds.add(entry.name);
+            skills.push({
+              id: entry.name,
+              name: metadata.name || entry.name,
+              description: metadata.description || "",
+              keywords: metadata.keywords || [],
+              category,
+            });
+          } catch {
+            // Skip invalid skill files
+          }
+        }
+      } catch {
+        // Skip inaccessible directories
+      }
+    }
+
+    this._skillCache = skills;
+    return skills;
+  }
+
+  /**
+   * Match a skill by keyword for auto-activation.
+   *
+   * @param {string} keyword - Keyword to match against skill keywords
+   * @returns {Promise<Object|null>} Matching skill or null
+   */
+  async _matchSkillByKeyword(keyword) {
+    const skills = await this.listAvailable();
+    const normalizedKeyword = keyword.toLowerCase();
+
+    for (const skill of skills) {
+      const keywords = (skill.keywords || []).map((k) => k.toLowerCase());
+      if (keywords.includes(normalizedKeyword)) {
+        return skill;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Parse SKILL.md frontmatter using the typed skill parser.
+   * Returns a flat metadata object with both generic and skill-specific fields.
+   *
+   * @param {string} content - SKILL.md content
+   * @returns {Object} Parsed metadata (flat key-value)
+   * @private
+   */
+  _parseFrontmatter(content) {
+    // N27 fix: extract frontmatter once, reuse for both parsers
+    const { raw } = extractFrontmatter(content);
+    if (!raw) return {};
+
+    // Use typed parser for skill-specific fields (handles multi-line arrays)
+    const { fields: skillFields } = parseSkillFrontmatter(content);
+    // Use generic parser for any additional fields not covered by typed parser
+    const { fields: genericFields } = parseFrontmatter(content);
+
+    // L5 fix: parse keywords independently from auto_activate
+    const keywords = parseYamlArray(raw, "keywords");
+
+    return {
+      ...genericFields,
+      name: skillFields.name || genericFields.name,
+      description: skillFields.description || genericFields.description,
+      auto_activate: skillFields.autoActivate || [],
+      keywords: keywords.length > 0 ? keywords : skillFields.autoActivate || [],
+      tool_reminders: skillFields.toolReminders || [],
+      file_triggers: skillFields.fileTriggers || [],
+      license: skillFields.license,
+      compatibility: skillFields.compatibility,
+      allowed_tools: skillFields.allowedTools || [],
+    };
+  }
+
+  /**
+   * Debug logger.
+   * @param {string} message
+   * @private
+   */
+  _log(message) {
+    if (this.debug) {
+      console.log(`[SkillDispatcher] ${message}`);
+    }
+  }
+}
+
+module.exports = { SkillDispatcher };