@caoscompanybr/merlin 3.5.0

package/.merlin-core/tools/commands/backup.js

@@ -0,0 +1,156 @@
+/**
+ * Merlin-Tools: backup — Create managed backup of project-owned data.
+ *
+ * Backs up thoughts, domain skills, project-config, and custom .claude commands
+ * to .merlin-backups/latest/ in the target project. Only keeps the most recent
+ * backup (rotates old ones).
+ *
+ * Usage:
+ *   node .merlin-core/tools/merlin-tools.js backup [target-path] [--dry-run]
+ *
+ * Examples:
+ *   node .merlin-core/tools/merlin-tools.js backup
+ *   node .merlin-core/tools/merlin-tools.js backup "/path/to/project"
+ *   node .merlin-core/tools/merlin-tools.js backup --dry-run
+ *
+ * @module tools/commands/backup
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  copyDirSync,
+  rmDirSync,
+  countFiles,
+  countRealThoughts,
+  extractVersion,
+  extractProjectName,
+  listSubdirs,
+} = require("./lib/fs-safe");
+
+async function run(_command, args, projectRoot) {
+  const dryRun = args.includes("--dry-run");
+  const filteredArgs = args.filter((a) => a !== "--dry-run");
+  const targetPath = filteredArgs[0]
+    ? path.resolve(filteredArgs[0])
+    : projectRoot;
+
+  const merlinDir = path.join(targetPath, ".merlin-core");
+  const claudeDir = path.join(targetPath, ".claude");
+  const backupsRoot = path.join(targetPath, ".merlin-backups");
+  const latestDir = path.join(backupsRoot, "latest");
+
+  // Validate
+  if (!fs.existsSync(merlinDir)) {
+    throw new Error(
+      `Not a Merlin project: ${targetPath}\n` +
+        "Missing .merlin-core/ directory.",
+    );
+  }
+
+  const version = extractVersion(path.join(merlinDir, "core-config.yaml"));
+  const projectName = extractProjectName(
+    path.join(merlinDir, "project-config.yaml"),
+  );
+
+  // Inventory what we'll back up
+  const thoughtsDir = path.join(merlinDir, "thoughts");
+  const domainDir = path.join(merlinDir, "skills", "domain");
+  const configFile = path.join(merlinDir, "project-config.yaml");
+  const commandsDir = path.join(claudeDir, "commands");
+
+  const inventory = {
+    thoughts: fs.existsSync(thoughtsDir) ? countRealThoughts(thoughtsDir) : 0,
+    domainSkills: fs.existsSync(domainDir) ? listSubdirs(domainDir).length : 0,
+    projectConfig: fs.existsSync(configFile),
+    claudeCommands: fs.existsSync(commandsDir) ? countFiles(commandsDir) : 0,
+  };
+
+  const result = {
+    project: projectName,
+    target: targetPath,
+    version,
+    timestamp: new Date().toISOString(),
+    location: latestDir,
+    dryRun,
+    backed: inventory,
+  };
+
+  if (dryRun) {
+    return result;
+  }
+
+  // Rotate: delete previous "latest" if exists
+  if (fs.existsSync(latestDir)) {
+    rmDirSync(latestDir);
+  }
+  fs.mkdirSync(latestDir, { recursive: true });
+
+  // 1. Thoughts
+  if (fs.existsSync(thoughtsDir)) {
+    copyDirSync(thoughtsDir, path.join(latestDir, "thoughts"));
+  }
+
+  // 2. Domain skills
+  if (fs.existsSync(domainDir)) {
+    copyDirSync(domainDir, path.join(latestDir, "domain-skills"));
+  }
+
+  // 3. project-config.yaml
+  if (fs.existsSync(configFile)) {
+    fs.copyFileSync(configFile, path.join(latestDir, "project-config.yaml"));
+  }
+
+  // 4. Custom .claude/commands
+  if (fs.existsSync(commandsDir)) {
+    copyDirSync(commandsDir, path.join(latestDir, "claude-commands"));
+  }
+
+  // 5. Write manifest
+  const manifest = {
+    timestamp: result.timestamp,
+    version,
+    project: projectName,
+    contents: inventory,
+  };
+  fs.writeFileSync(
+    path.join(latestDir, "backup-manifest.json"),
+    JSON.stringify(manifest, null, 2),
+  );
+
+  // 6. Verify backup integrity
+  const verifiedThoughts = countRealThoughts(path.join(latestDir, "thoughts"));
+  if (verifiedThoughts < inventory.thoughts) {
+    result.warning = `Thought backup may be incomplete: expected ${inventory.thoughts}, got ${verifiedThoughts}`;
+  }
+
+  return result;
+}
+
+function formatHuman(result) {
+  const lines = [];
+  const mode = result.dryRun ? "DRY RUN" : "BACKUP";
+  lines.push(`\n=== Merlin ${mode}: ${result.project} ===`);
+  lines.push(`Target:    ${result.target}`);
+  lines.push(`Version:   ${result.version}`);
+  lines.push(`Timestamp: ${result.timestamp}`);
+  lines.push(`Location:  ${result.location}`);
+  lines.push("");
+
+  const b = result.backed;
+  lines.push("Contents:");
+  lines.push(`  ✓ thoughts/ (${b.thoughts} files)`);
+  lines.push(`  ✓ skills/domain/ (${b.domainSkills} skills)`);
+  lines.push(`  ✓ project-config.yaml (${b.projectConfig ? "yes" : "no"})`);
+  lines.push(`  ✓ .claude/commands/ (${b.claudeCommands} files)`);
+
+  if (result.warning) {
+    lines.push(`\n  ⚠ ${result.warning}`);
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman };

package/.merlin-core/tools/commands/certify-process.js

@@ -0,0 +1,196 @@
+/**
+ * certify-process -- Run the 6-gate certification pipeline on a PROCESSO (Constitution XIV).
+ *
+ * Gates:
+ *   G1 schema            (auto)  frontmatter + ```json definition well-formed
+ *   G2 safety            (auto)  every step safety-tagged; no absolute step is autonomous
+ *   G5 secret-scan       (auto)  no secrets in the process file (Article XI / XIV-c floor)
+ *   G3/G4 rehearsal      (attest) operator confirms `/run-process --dry-run` x2 (end-state + idempotency)
+ *   G6 human sign-off    (gate)   explicit --approve "Name" — the relocated Article VII gate
+ *
+ * Only on ALL gates passing does the process become `status: certified` with a signature
+ * over its step list. Deterministic gates run automatically and fail-closed; the rehearsal
+ * and sign-off are explicit human actions (the "bureaucratic" intent).
+ *
+ * Usage:
+ *   certify-process <process-file>                      → run auto gates, report readiness
+ *   certify-process <process-file> --rehearsed          → + attest rehearsal/idempotency
+ *   certify-process <process-file> --rehearsed --approve "Name"  → certify + sign
+ *
+ * @module tools/commands/certify-process
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { loadProcess } = require("../../core/process/process-file");
+const { sign } = require("../../core/process/signature");
+const { scanForSecrets } = require("../../core/process/secret-scan");
+
+const SAFETY = ["low", "medium", "high", "absolute"];
+
+/** Update or insert flat scalar keys in the frontmatter block. */
+function setFrontmatterScalars(content, updates) {
+  const m = content.match(/^(---\r?\n)([\s\S]*?)(\r?\n---\r?\n?)/);
+  if (!m) throw new Error("No frontmatter block found");
+  let fm = m[2];
+  for (const [key, value] of Object.entries(updates)) {
+    const line = `${key}: ${value}`;
+    const re = new RegExp(`^${key}\\s*:.*$`, "m");
+    if (re.test(fm)) fm = fm.replace(re, line);
+    else fm = `${fm}\n${line}`;
+  }
+  return m[1] + fm + m[3] + content.slice(m[0].length);
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+async function run(_command, args, projectRoot) {
+  const positionals = args.filter((a) => !a.startsWith("--"));
+  const rawPath = positionals[0];
+  if (!rawPath) {
+    throw new Error(
+      'Usage: certify-process <process-file> [--rehearsed] [--approve "Name"]',
+    );
+  }
+  const filePath = path.isAbsolute(rawPath)
+    ? rawPath
+    : path.join(projectRoot, rawPath);
+  if (!fs.existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
+
+  // --approve "Name"  or  --approve=Name
+  let approver = null;
+  const approveEq = args.find((a) => a.startsWith("--approve="));
+  if (approveEq) approver = approveEq.slice("--approve=".length);
+  else if (args.includes("--approve")) {
+    const i = args.indexOf("--approve");
+    if (args[i + 1] && !args[i + 1].startsWith("--")) approver = args[i + 1];
+  }
+  const rehearsed = args.includes("--rehearsed");
+
+  const { content, frontmatter, definition } = loadProcess(filePath);
+  const gates = [];
+
+  if (frontmatter.status === "deprecated") {
+    return {
+      certified: false,
+      status: "deprecated",
+      gates,
+      error: "process is deprecated — cannot certify",
+    };
+  }
+
+  const stop = (gate, errors) => {
+    gates.push({ gate, passed: false, errors });
+    return { certified: false, status: frontmatter.status || "draft", gates };
+  };
+
+  // G1 — schema
+  const g1 = [];
+  if (!frontmatter.title || String(frontmatter.title).length < 5)
+    g1.push("frontmatter.title missing or < 5 chars");
+  if (!frontmatter.trigger_mode) g1.push("frontmatter.trigger_mode missing");
+  if (!definition) g1.push("missing or invalid ```json definition body block");
+  else {
+    if (!Array.isArray(definition.steps) || definition.steps.length < 1)
+      g1.push("definition.steps must be a non-empty array");
+    if (
+      !Array.isArray(definition.success_criteria) ||
+      definition.success_criteria.length < 1
+    )
+      g1.push("definition.success_criteria must be a non-empty array");
+  }
+  if (g1.length) return stop("G1-schema", g1);
+  gates.push({ gate: "G1-schema", passed: true });
+
+  // G2 — safety completeness (enforces the Article XI floor at authoring time)
+  const g2 = [];
+  definition.steps.forEach((s, i) => {
+    const tag = s.id || `#${i}`;
+    if (!s.id) g2.push(`step ${tag}: missing id`);
+    if (!s.description) g2.push(`step ${tag}: missing description`);
+    if (!SAFETY.includes(s.safety))
+      g2.push(`step ${tag}: safety must be one of ${SAFETY.join("|")}`);
+    if (s.safety === "absolute" && s.autonomous === true)
+      g2.push(
+        `step ${tag}: safety:absolute can NEVER be autonomous (Article XI floor)`,
+      );
+  });
+  if (g2.length) return stop("G2-safety", g2);
+  gates.push({ gate: "G2-safety", passed: true });
+
+  // G5 — secret scan (Article XI / XIV-c)
+  const findings = scanForSecrets(content);
+  if (findings.length)
+    return stop(
+      "G5-secret-scan",
+      findings.map((f) => `potential secret: ${f.sample}`),
+    );
+  gates.push({ gate: "G5-secret-scan", passed: true });
+
+  // G3/G4 — rehearsal + idempotency (operator-attested; executor --dry-run is the vehicle)
+  if (!rehearsed) {
+    gates.push({
+      gate: "G3/G4-rehearsal",
+      passed: false,
+      errors: [
+        "not attested — run `/run-process <slug> --dry-run` twice (verify end-state + idempotency), then re-run with --rehearsed",
+      ],
+    });
+    return {
+      certified: false,
+      status: frontmatter.status || "draft",
+      gates,
+      next: "attest rehearsal with --rehearsed",
+    };
+  }
+  gates.push({
+    gate: "G3/G4-rehearsal",
+    passed: true,
+    note: "operator-attested",
+  });
+
+  // G6 — human sign-off (the relocated Article VII gate)
+  if (!approver) {
+    gates.push({
+      gate: "G6-signoff",
+      passed: false,
+      errors: [
+        'awaiting explicit human sign-off — re-run with --approve "Your Name"',
+      ],
+    });
+    return {
+      certified: false,
+      status: frontmatter.status || "draft",
+      gates,
+      next: 'sign off with --approve "Name"',
+    };
+  }
+  gates.push({ gate: "G6-signoff", passed: true, certified_by: approver });
+
+  // All gates passed → certify + sign
+  const signature = sign(definition.steps);
+  const updated = setFrontmatterScalars(content, {
+    status: "certified",
+    certified_by: `"${approver}"`,
+    certified_date: today(),
+    check_passed: true,
+    signature,
+  });
+  fs.writeFileSync(filePath, updated);
+
+  return {
+    certified: true,
+    status: "certified",
+    signature,
+    certified_by: approver,
+    certified_date: today(),
+    gates,
+    note: "Process certified. It may now run autonomously via /run-process under Article XIV.",
+  };
+}
+
+module.exports = { run, setFrontmatterScalars };

package/.merlin-core/tools/commands/convert.js

@@ -0,0 +1,87 @@
+/**
+ * CONVERT mode entry — thin wrapper around upgrade.run() for sibling-copy scenarios.
+ *
+ * Differs from install.js: source is NOT auto-detected; must be provided explicitly.
+ * Matches the bash convert-to-merlin.sh requirement of a MERLIN_SOURCE positional.
+ *
+ * Two invocation paths:
+ *   1. Via merlin-tools.js CLI:
+ *        node .merlin-core/tools/merlin-tools.js convert [TARGET] [--dry-run] [--flatten-nesting]
+ *      projectRoot is the SOURCE from merlin-tools.js perspective (gestao-merlin root).
+ *
+ *   2. Direct:
+ *        node convert.js TARGET SOURCE [flags]
+ *      Both target and source must be positional. Useful for ad-hoc invocation.
+ *
+ * @module tools/commands/convert
+ */
+
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const upgrade = require("./upgrade");
+
+/**
+ * Entry called by merlin-tools.js or test code.
+ *
+ * @param {string} command  Subcommand name ("convert")
+ * @param {string[]} args   Remaining CLI args (positional + flags)
+ * @param {string} projectRoot  Source framework root
+ */
+async function run(command, args, projectRoot) {
+  const positionals = args.filter((a) => !a.startsWith("-"));
+  const flags = args.filter((a) => a.startsWith("-"));
+  const target = positionals[0] || process.cwd();
+
+  return upgrade.run("upgrade", [target, ...flags], projectRoot);
+}
+
+function formatHuman(result) {
+  return upgrade.formatHuman(result);
+}
+
+// Direct invocation: expect 2 positionals (TARGET, SOURCE) plus optional flags
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const positionals = argv.filter((a) => !a.startsWith("-"));
+  const flags = argv.filter((a) => a.startsWith("-"));
+
+  if (positionals.length < 2) {
+    console.error(
+      "Usage: node convert.js TARGET_DIR SOURCE_DIR [--dry-run] [--yes] [--flatten-nesting]",
+    );
+    console.error("");
+    console.error(
+      "  TARGET_DIR   Project to convert (must not yet have .merlin-core/)",
+    );
+    console.error("  SOURCE_DIR   Gestao Merlin framework root");
+    process.exit(1);
+  }
+
+  const [target, source] = positionals;
+
+  if (
+    !fs.existsSync(path.join(source, ".merlin-core", "framework-config.yaml"))
+  ) {
+    console.error(
+      `CONVERT error: SOURCE_DIR ${source} does not contain ` +
+        `.merlin-core/framework-config.yaml.`,
+    );
+    process.exit(1);
+  }
+
+  run("convert", [target, ...flags], source)
+    .then((result) => {
+      if (result && result.errors && result.errors.length > 0) {
+        process.exit(1);
+      }
+      process.exit(0);
+    })
+    .catch((err) => {
+      console.error(`CONVERT failed: ${err.message}`);
+      process.exit(1);
+    });
+}
+
+module.exports = { run, formatHuman };

package/.merlin-core/tools/commands/cron.js

@@ -0,0 +1,147 @@
+/**
+ * cron -- manage and run native scheduled agent turns (v3.4)
+ *
+ *   merlin cron list
+ *   merlin cron add --name "Check agenda" --expr "0 8 * * *" --tz America/Sao_Paulo --message "..."
+ *   merlin cron add --name "One off"      --at 2026-07-01T09:00:00-03:00      --message "..."
+ *   merlin cron run <id>            # dispatch the job now (isolated, Sonnet)
+ *   merlin cron remove <id>
+ *   merlin cron due                 # list jobs due right now
+ *   merlin cron watchdog            # audit job health (failing / needs-alert)
+ *
+ * The store is `.merlin/crons.json` (CLI is the source of truth). The
+ * dashboard timer (deferred) ticks and shells `merlin cron run <id>`.
+ *
+ * @module tools/commands/cron
+ */
+
+"use strict";
+
+const {
+  CronStore,
+  isDue,
+  runJob,
+  watchdog,
+} = require("../../core/execution/cron-engine");
+
+/** Parse `--key value` / `--flag` pairs from an arg list. */
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    }
+  }
+  return flags;
+}
+
+async function run(_command, args, projectRoot) {
+  const sub = args[0] || "list";
+  const rest = args.slice(1);
+  const store = new CronStore({ projectRoot });
+
+  switch (sub) {
+    case "list":
+      return { success: true, jobs: store.list() };
+
+    case "due": {
+      const now = new Date();
+      return {
+        success: true,
+        now: now.toISOString(),
+        jobs: store.list().filter((j) => isDue(j, now)),
+      };
+    }
+
+    case "add": {
+      const f = parseFlags(rest);
+      const job = {
+        name: f.name,
+        schedule: f.at
+          ? { kind: "at", at: f.at }
+          : { kind: "cron", expr: f.expr, tz: f.tz || null },
+        payload: {
+          kind: "agentTurn",
+          message: f.message,
+          agent: f.agent || "@merlin-master",
+          model: f.model || null,
+        },
+        enabled: f.disabled ? false : true,
+      };
+      const added = store.add(job);
+      return { success: true, added };
+    }
+
+    case "remove": {
+      const id = rest[0];
+      if (!id) return { success: false, error: "usage: cron remove <id>" };
+      return { success: store.remove(id), id };
+    }
+
+    case "run": {
+      const id = rest[0];
+      if (!id) return { success: false, error: "usage: cron run <id>" };
+      const job = store.get(id);
+      if (!job) return { success: false, error: `no such job: ${id}` };
+
+      // Lazy-require dispatch deps so `list`/`add` stay cheap.
+      const {
+        SubagentDispatcher,
+      } = require("../../core/execution/subagent-dispatcher");
+      const { ModelRouter } = require("../../core/execution/model-router");
+      const {
+        GuardrailEngine,
+      } = require("../../core/execution/guardrail-engine");
+      const dispatcher = new SubagentDispatcher({
+        rootPath: projectRoot,
+        modelRouter: new ModelRouter(),
+        guardrailEngine: new GuardrailEngine({ projectRoot }),
+      });
+
+      const result = await runJob(job, { dispatcher, store, now: new Date() });
+      return { success: result.ok, id, result };
+    }
+
+    case "watchdog": {
+      const audit = watchdog(store);
+      return {
+        success: true,
+        healthy: audit.healthy.map((j) => j.id),
+        failing: audit.failing.map((j) => j.id),
+        needsAlert: audit.needsAlert.map((j) => j.id),
+      };
+    }
+
+    default:
+      return { success: false, error: `unknown cron subcommand: ${sub}` };
+  }
+}
+
+function formatHuman(result) {
+  if (result.jobs) {
+    if (result.jobs.length === 0) return "No cron jobs.";
+    return result.jobs
+      .map((j) => {
+        const sched =
+          j.schedule.kind === "cron"
+            ? `${j.schedule.expr}${j.schedule.tz ? " " + j.schedule.tz : ""}`
+            : `@ ${j.schedule.at}`;
+        const status = j.enabled ? "" : " (disabled)";
+        const last = j.last_result ? ` [last: ${j.last_result}]` : "";
+        return `${j.id} — ${j.name}${status}: ${sched}${last}`;
+      })
+      .join("\n");
+  }
+  if (!result.success) return `FAILED: ${result.error}`;
+  return JSON.stringify(result, null, 2);
+}
+
+module.exports = { run, formatHuman };

package/.merlin-core/tools/commands/disable.js

@@ -0,0 +1,73 @@
+/**
+ * disable -- Disable / uninstall a Merlin Module (§7.5 lifecycle).
+ *
+ * CommonJS bridge to the ESM orchestrator (disable-module.mjs). Reversible by
+ * default (disable flag → pause schedulers → revoke webhooks → archive-not-delete);
+ * `--purge` adds the irreversible delete step. framework-skill executes (removes the
+ * config entry); cloud deploy_kinds plan-emit via PlanOnlyDeployer. Dry-run default.
+ *
+ * Usage:
+ *   node .merlin-core/tools/merlin-tools.js disable --module=<id> [--apply]
+ *   node .merlin-core/tools/merlin-tools.js disable --module=<id> --workspace=<ws> [--apply] [--purge]
+ *
+ * @module tools/commands/disable
+ */
+
+"use strict";
+
+const path = require("path");
+const { pathToFileURL } = require("url");
+
+function val(args, flag) {
+  const eq = args.find((a) => a.startsWith(`${flag}=`));
+  if (eq) return eq.split("=").slice(1).join("=");
+  const i = args.indexOf(flag);
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--")
+    ? args[i + 1]
+    : undefined;
+}
+
+async function run(_command, args, projectRoot) {
+  const url = pathToFileURL(
+    path.join(__dirname, "..", "disable-module.mjs"),
+  ).href;
+  const { disableModule } = await import(url);
+  return disableModule({
+    projectRoot,
+    moduleId: val(args, "--module"),
+    workspace: val(args, "--workspace"),
+    firebaseProject: val(args, "--firebase-project"),
+    apply: args.includes("--apply"),
+    purge: args.includes("--purge"),
+    log: (m) => console.log(m),
+  });
+}
+
+function formatHuman(result) {
+  if (!result.ok) {
+    return `✗ disable failed${result.moduleId ? ` (${result.moduleId})` : ""}: ${result.error}`;
+  }
+  const lines = [
+    `module: ${result.moduleId}  deploy_kind: ${result.deploy_kind}  applied: ${result.applied}` +
+      (result.reversible === false
+        ? "  ⚠ PURGE (irreversible)"
+        : "  (reversible)"),
+  ];
+  if (result.deploy_kind === "framework-skill" && result.deactivation) {
+    lines.push(
+      result.deactivation.changed
+        ? `deactivation: ${result.applied ? "removed" : "would remove"} ${result.moduleId} from modules.enabled`
+        : `deactivation: not enabled (no-op)`,
+    );
+  }
+  if (result.steps) {
+    lines.push(
+      `teardown plan (${result.steps.length} steps, executed: ${result.applied}):`,
+    );
+    for (const s of result.steps) lines.push(`    ${s.name}: ${s.command}`);
+    if (result.note) lines.push(`note: ${result.note}`);
+  }
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman };