@caoscompanybr/merlin 3.5.0

package/.merlin-core/framework-config.yaml

@@ -0,0 +1,148 @@
+# ============================================
+# Merlin Framework Configuration (Level 1)
+# ============================================
+# DO NOT EDIT — This file is part of the Merlin framework.
+# Override values in project-config.yaml or local-config.yaml.
+#
+# Level: L1 (Framework)
+# Mutability: Read-only (shipped with package)
+# Git status: Committed (framework source)
+# ============================================
+
+metadata:
+  name: "Gestao Merlin"
+  framework_version: "3.5.0"
+
+markdownExploder: true
+
+# --- Resource Locations ---
+resource_locations:
+  agents_dir: ".merlin-core/development/agents"
+  tasks_dir: ".merlin-core/development/tasks"
+  templates_dir: ".merlin-core/development/templates"
+  checklists_dir: ".merlin-core/development/checklists"
+  workflows_dir: ".merlin-core/development/workflows"
+  commands_dir: ".merlin-core/commands"
+  skills_dir: ".merlin-core/skills"
+  thoughts_dir: ".merlin-core/thoughts"
+  scripts:
+    core: ".merlin-core/core"
+    development: ".merlin-core/development/scripts"
+    infrastructure: ".merlin-core/infrastructure/scripts"
+  data_dir: ".merlin-core/data"
+  elicitation_dir: ".merlin-core/elicitation"
+  squads_template_dir: "templates/squad"
+
+# --- Performance Defaults ---
+performance_defaults:
+  lazy_loading:
+    enabled: true
+    heavy_sections:
+      - squads
+      - registry
+  git:
+    show_config_warning: true
+    cache_time_seconds: 300
+
+# --- Utility Scripts Registry ---
+utility_scripts_registry:
+  helpers:
+    - capability-analyzer
+    - code-quality-improver
+    - compatibility-checker
+    - component-metadata
+    - conflict-manager
+    - coverage-analyzer
+    - dependency-analyzer
+    - diff-generator
+    - framework-analyzer
+    - git-wrapper
+    - manifest-preview
+    - performance-analyzer
+    - redundancy-analyzer
+    - refactoring-suggester
+    - template-validator
+    - test-quality-assessment
+    - validate-filenames
+    - version-tracker
+  executors:
+    - approval-workflow
+    - branch-manager
+    - commit-message-generator
+    - component-generator
+    - component-search
+    - conflict-resolver
+    - dependency-impact-analyzer
+    - documentation-synchronizer
+    - performance-optimizer
+    - rollback-handler
+    - test-generator
+    - test-updater
+  framework:
+    - elicitation-engine
+    - elicitation-session-manager
+    - metrics-tracker
+    - pattern-learner
+    - template-engine
+    - transaction-manager
+
+# --- Alkimia Engine Defaults ---
+alkimia:
+  layers:
+    l0_constitution:
+      enabled: true
+      priority: 100
+    l1_global:
+      enabled: true
+      priority: 90
+    l2_agent:
+      enabled: true
+      priority: 80
+    l3_workflow:
+      enabled: true
+      priority: 70
+    l4_task:
+      enabled: true
+      priority: 60
+    l5_squad:
+      enabled: true
+      priority: 50
+    l6_skill:
+      enabled: true
+      priority: 40
+      auto_activation: true
+    l7_star_command:
+      enabled: true
+      priority: 30
+  context_brackets:
+    FRESH:
+      max_percentage: 25
+      all_layers: true
+    MODERATE:
+      max_percentage: 50
+      trim_optional: true
+    DEPLETED:
+      max_percentage: 75
+      essential_only: true
+    CRITICAL:
+      max_percentage: 100
+      constitution_and_task_only: true
+
+# --- Quality Gate Defaults ---
+quality_gates:
+  layer1:
+    enabled: true
+    checks:
+      - lint
+      - test
+      - typecheck
+      - build
+  layer2:
+    enabled: true
+    checks:
+      - automated_review
+      - coverage_threshold
+      - security_scan
+  layer3:
+    enabled: true
+    require_human: true

package/.merlin-core/hooks/README.md

@@ -0,0 +1,16 @@
+# Git Hooks
+
+The hooks module provides Git hooks for quality enforcement at critical points in the development workflow. Pre-commit hooks validate code before staging, commit-msg hooks ensure consistent commit messages, and pre-push hooks perform final checks before remote operations.
+
+## Contents
+
+- **pre-commit** - Validates code style, tests, and security before commit
+- **commit-msg** - Enforces commit message format and standards
+- **pre-push** - Final quality checks before pushing to remote
+- **hook-installer.js** - Utility for installing and managing hooks
+- **hooks-config.json** - Configuration for hook behavior
+
+## Related
+
+- [Quality Gates](../core/quality-gates/README.md)
+- [Config](../core/config/README.md)

package/.merlin-core/hooks/precompact-memory-flush.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Merlin — PreCompact memory-flush hook (v3.4 autonomy/memory).
+ *
+ * Fires when Claude Code is about to compact the conversation (the CRITICAL
+ * context moment). Injects an instruction reminding the session to persist
+ * durable memory BEFORE context is lost — porting MerlinBot's inviolable rule
+ * ("antes de compactar → extrair lições, decisões e pendências").
+ *
+ * Input (stdin): { session_id, transcript_path, trigger:"manual"|"auto", ... }
+ * Output (stdout): { hookSpecificOutput: { hookEventName:"PreCompact",
+ *                    additionalContext: "<flush instruction>" } }
+ *
+ * Deterministic, no network. Registered (opt-in) into a project's
+ * `.claude/settings.json` `hooks.PreCompact`.
+ *
+ * Runs as CommonJS (nearest package.json = `.merlin-core/package.json`).
+ *
+ * @module hooks/precompact-memory-flush
+ */
+
+"use strict";
+
+const FLUSH_INSTRUCTION = [
+  "[MEMORY FLUSH — before compaction]",
+  "Context is about to be compacted. Information not written to a file is lost.",
+  "Before continuing, extract and persist anything durable from this session:",
+  "  - Decisions made → .merlin-core/thoughts/shared/decisions/",
+  "  - Lessons / gotchas learned → .merlin-core/thoughts/shared/learnings/ (tag ttl: permanent or 30d)",
+  "  - Open / pending items → .merlin-core/thoughts/shared/reminders/ or objectives/",
+  "  - If mid-task, write a handoff → .merlin-core/thoughts/shared/handoffs/",
+  "Then rebuild the index (`merlin index`). Skip only what is already saved.",
+].join("\n");
+
+/**
+ * Build the PreCompact hook output.
+ * @param {Object} [payload] - the PreCompact stdin payload (reserved)
+ * @returns {Object} hookSpecificOutput envelope
+ */
+function buildFlushOutput(payload) {
+  const trigger = (payload && payload.trigger) || "auto";
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreCompact",
+      additionalContext:
+        FLUSH_INSTRUCTION +
+        (trigger === "manual" ? "\n(Manual compaction requested.)" : ""),
+    },
+  };
+}
+
+async function main() {
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+  let payload = {};
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    payload = {};
+  }
+  process.stdout.write(JSON.stringify(buildFlushOutput(payload)));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { buildFlushOutput, FLUSH_INSTRUCTION };

package/.merlin-core/hooks/pretooluse-remote-approve.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/* global AbortController */
+/**
+ * Merlin — PreToolUse remote-approve hook (Phase 2 APPROVE).
+ *
+ * Installed (opt-in, per project) into a project's `.claude/settings.json`
+ * `hooks.PreToolUse`. When Claude Code is about to use a routed tool, it runs
+ * this script with the PreToolUse payload on stdin:
+ *   { session_id, cwd, tool_name, tool_input, permission_mode }
+ * The script asks the Mission Control dashboard bridge for a verdict (the owner
+ * taps Approve/Deny on the panel/phone) and emits the decision Claude obeys:
+ *   { hookSpecificOutput: { hookEventName:"PreToolUse",
+ *                           permissionDecision:"allow"|"deny"|"ask",
+ *                           permissionDecisionReason: "…" } }
+ *
+ * Safety (Constitution VII/XI + plan's conservative-security decision):
+ *   • Per-project opt-in via `<cwd>/.merlin/remote-approve.json` (enabled+token).
+ *     Not enabled / no config  →  `ask` (inert: fall back to the normal prompt).
+ *   • Enabled but the bridge errors / is unreachable / times out  →  `deny`.
+ *     NEVER silently allow.
+ *   • ABSOLUTE/destructive tools are forced to interactive `ask` by the bridge.
+ *
+ * Runs as CommonJS (nearest package.json = `.merlin-core/package.json`).
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+
+const DEFAULT_DASHBOARD = "http://127.0.0.1:3939";
+// Abort before Claude Code's ~600s hook cap so we can fail safe to deny.
+const FETCH_TIMEOUT_MS = 9 * 60 * 1000;
+
+function emit(decision, reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: decision,
+        permissionDecisionReason: reason || "",
+      },
+    }),
+  );
+  process.exit(0);
+}
+
+function readConfig(cwd) {
+  try {
+    const p = path.join(cwd || process.cwd(), ".merlin", "remote-approve.json");
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+
+  let payload;
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    // Can't even read the request — don't block normal work; defer to interactive.
+    return emit("ask", "remote-approve: unparseable hook input");
+  }
+
+  const cwd = payload.cwd || process.cwd();
+  const cfg = readConfig(cwd);
+
+  // Opt-in gate: if remote-approve isn't enabled for this project, stay inert.
+  if (!cfg || cfg.enabled !== true || !cfg.token) {
+    return emit("ask", "remote-approve: not enabled for this project");
+  }
+
+  const dashboardUrl = (cfg.dashboardUrl || DEFAULT_DASHBOARD).replace(
+    /\/+$/,
+    "",
+  );
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+  try {
+    const res = await fetch(`${dashboardUrl}/api/approvals/request`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-merlin-approve-token": cfg.token,
+      },
+      body: JSON.stringify({
+        projectPath: cwd,
+        sessionId: payload.session_id || "",
+        toolName: payload.tool_name || "",
+        toolInput: payload.tool_input || {},
+        token: cfg.token,
+      }),
+      signal: controller.signal,
+    });
+    const data = await res.json().catch(() => ({}));
+    const decision = ["allow", "deny", "ask"].includes(data.decision)
+      ? data.decision
+      : "deny";
+    return emit(decision, data.reason || "remote-approve bridge");
+  } catch (e) {
+    // Enabled but the bridge failed → fail safe to deny (never silently allow).
+    return emit(
+      "deny",
+      `remote-approve: bridge unreachable (${e && e.message})`,
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+main().catch((e) => emit("deny", `remote-approve: ${e && e.message}`));

package/.merlin-core/hooks/spikes/spike-b-hook.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Phase 0 — Spike B: the PreToolUse hook half.
+ *
+ * Proves an interactive Claude Code session in a VS Code terminal PAUSES at a
+ * tool call, waits on an external decision, then RUNS on allow / BLOCKS on deny.
+ *
+ * It reads the PreToolUse JSON on stdin ({session_id, cwd, tool_name,
+ * tool_input, permission_mode}), POSTs it to the local stub (spike-b-stub.js),
+ * long-polls until the stub resolves, and emits the verdict that Claude Code
+ * obeys. Fail-safe: any error/unreachable → deny (never silently allow).
+ *
+ * Wire-up (in a THROWAWAY test project's .claude/settings.json):
+ *   {
+ *     "permissions": { "allow": ["Bash(echo:*)"] },
+ *     "hooks": {
+ *       "PreToolUse": [{ "matcher": "Bash", "hooks": [
+ *         { "type": "command",
+ *           "command": "node \"/path/to/project/.merlin-core/hooks/spikes/spike-b-hook.js\"" }
+ *       ]}]
+ *     }
+ *   }
+ * Start the stub first: node .merlin-core/hooks/spikes/spike-b-stub.js
+ * Then in the test project run `claude` and ask it to `echo hi`. It should hang
+ * until you write allow/deny into spike-b-decision.txt (the stub watches it).
+ */
+const STUB = process.env.SPIKE_B_STUB || "http://127.0.0.1:8787/request";
+
+function emit(decision, reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: decision, // "allow" | "deny" | "ask"
+        permissionDecisionReason: reason,
+      },
+    }),
+  );
+  process.exit(0);
+}
+
+async function main() {
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+  let payload = {};
+  try {
+    payload = JSON.parse(raw || "{}");
+  } catch {
+    return emit("deny", "spike-b: unparseable hook stdin");
+  }
+  process.stderr.write(
+    `[spike-b] tool=${payload.tool_name} cwd=${payload.cwd} — asking stub…\n`,
+  );
+  try {
+    const res = await fetch(STUB, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    const data = await res.json();
+    const decision = ["allow", "deny", "ask"].includes(data.decision)
+      ? data.decision
+      : "deny";
+    return emit(decision, data.reason || "spike-b stub");
+  } catch (e) {
+    return emit("deny", `spike-b: stub unreachable (${e.message})`);
+  }
+}
+
+main();

package/.merlin-core/hooks/spikes/spike-b-stub.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Phase 0 — Spike B: the bridge stub half.
+ *
+ * Minimal local endpoint the spike-b hook long-polls. On POST /request it waits
+ * until a decision appears in `spike-b-decision.txt` (sitting next to this file)
+ * — letting you "inject yes" by writing `allow` (or `deny`) into that file while
+ * the interactive `claude` session is paused. Default after 120s: deny.
+ *
+ * This is the throwaway predecessor of the real bridge (Phase 2:
+ * routes/approvals.ts). Run: node .merlin-core/hooks/spikes/spike-b-stub.js
+ */
+const http = require("node:http");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const PORT = Number(process.env.SPIKE_B_PORT || 8787);
+const DECISION_FILE = path.join(__dirname, "spike-b-decision.txt");
+const MAX_WAIT_MS = 120_000;
+
+function readDecision() {
+  try {
+    const v = fs.readFileSync(DECISION_FILE, "utf-8").trim().toLowerCase();
+    if (["allow", "deny", "ask"].includes(v)) return v;
+  } catch {
+    /* not written yet */
+  }
+  return null;
+}
+
+const server = http.createServer((req, res) => {
+  if (req.method !== "POST" || !req.url.startsWith("/request")) {
+    res.writeHead(404).end();
+    return;
+  }
+  let body = "";
+  req.on("data", (c) => (body += c));
+  req.on("end", () => {
+    try {
+      fs.writeFileSync(DECISION_FILE, ""); // clear any stale decision
+    } catch {
+      /* ignore */
+    }
+    console.log(`[stub] request received — waiting for ${DECISION_FILE}`);
+    const started = Date.now();
+    const poll = setInterval(() => {
+      const d = readDecision();
+      if (d) {
+        clearInterval(poll);
+        console.log(`[stub] resolving → ${d}`);
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ decision: d, reason: `spike-b: ${d}` }));
+      } else if (Date.now() - started > MAX_WAIT_MS) {
+        clearInterval(poll);
+        console.log("[stub] timeout → deny");
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(
+          JSON.stringify({ decision: "deny", reason: "spike-b: timeout" }),
+        );
+      }
+    }, 500);
+  });
+});
+
+server.listen(PORT, "127.0.0.1", () =>
+  console.log(
+    `[stub] listening http://127.0.0.1:${PORT}/request\n` +
+      `       inject a verdict:  echo allow > "${DECISION_FILE}"`,
+  ),
+);

package/.merlin-core/index.js

@@ -0,0 +1,91 @@
+/**
+ * Merlin Core Module - Entry Point
+ *
+ * Provides centralized exports for all core framework functionality.
+ * This module contains the essential runtime components that all other
+ * modules depend on.
+ *
+ * @module @gestao-merlin/core
+ * @version 3.0.0
+ */
+
+"use strict";
+
+// Config subsystem
+const configResolver = require("./core/config/config-resolver");
+const configLoader = require("./core/config/config-loader");
+
+// Alkimia
+const alkimia = require("./core/alkimia/engine");
+
+// Orchestration
+const orchestrator = require("./core/orchestration/master-orchestrator");
+const decisionTree = require("./core/orchestration/decision-tree");
+const workflowExecutor = require("./core/orchestration/workflow-executor");
+const sessionState = require("./core/orchestration/session-state");
+
+// Execution
+const buildLoop = require("./core/execution/autonomous-build-loop");
+const buildOrchestrator = require("./core/execution/build-orchestrator");
+const parallelExecutor = require("./core/execution/parallel-executor");
+
+// Quality & Approval
+const approvalEngine = require("./core/approval/approval-engine");
+const precommit = require("./core/quality-gates/layer1-precommit");
+const prAutomation = require("./core/quality-gates/layer2-pr-automation");
+const humanReview = require("./core/quality-gates/layer3-human-review");
+
+// MCP
+const mcpRegistry = require("./core/mcp/mcp-registry");
+const capabilityMapper = require("./core/mcp/capability-mapper");
+const mcpConnector = require("./core/mcp/mcp-connector");
+
+// Infrastructure
+const healthEngine = require("./core/health-check/health-engine");
+const serviceRegistry = require("./core/registry/service-registry");
+const eventBus = require("./core/events/event-bus");
+
+/**
+ * Core module exports
+ */
+module.exports = {
+  // Config
+  config: configResolver,
+  configLoader,
+
+  // Alkimia
+  alkimia,
+
+  // Orchestration
+  orchestrator,
+  decisionTree,
+  workflowExecutor,
+  sessionState,
+
+  // Execution
+  buildLoop,
+  buildOrchestrator,
+  parallelExecutor,
+
+  // Quality & Approval
+  approvalEngine,
+  qualityGates: {
+    precommit,
+    prAutomation,
+    humanReview,
+  },
+
+  // MCP
+  mcpRegistry,
+  capabilityMapper,
+  mcpConnector,
+
+  // Infrastructure
+  healthEngine,
+  serviceRegistry,
+  eventBus,
+
+  // Version info
+  version: "3.0.0",
+  moduleName: "merlin-core",
+};

package/.merlin-core/local-config.yaml.template

@@ -0,0 +1,31 @@
+# ============================================
+# Merlin Local Configuration (Level 3)
+# ============================================
+# COPY THIS FILE to local-config.yaml and customize.
+# Values here override project-config.yaml for your machine only.
+#
+# Level: L3 (Local)
+# Mutability: Personal overrides
+# Git status: GITIGNORED (never committed)
+# ============================================
+
+# --- User Profile ---
+# user_profile: advanced  # beginner | intermediate | advanced
+
+# --- Local MCP Servers ---
+# mcp:
+#   servers:
+#     my-local-server:
+#       command: node
+#       args: ["/path/to/server.js"]
+#       env:
+#         API_KEY: "your-key-here"
+
+# --- Approval Channel Override ---
+# approval:
+#   defaultChannel: slack  # cli | slack | web
+
+# --- IDE Override ---
+# ide:
+#   selected:
+#     - vscode