@caoscompanybr/merlin 3.5.0

package/.merlin-core/tools/commands/prune-feedback.js

@@ -0,0 +1,114 @@
+/**
+ * prune-feedback -- enforce FIFO-30 retention on the feedback thought-type (v3.4)
+ *
+ * Keeps the newest N (default 30) feedback entries PER DOMAIN and removes the
+ * rest — the MerlinBot immune-system rule ("max 30 entradas por arquivo, FIFO").
+ * Feedback is ephemeral by design; durable signal is promoted to learnings/decisions.
+ *
+ *   merlin prune-feedback [--limit 30] [--dry-run]
+ *
+ * @module tools/commands/prune-feedback
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_LIMIT = 30;
+
+/**
+ * Pure selector: given feedback entries, return those to prune (oldest beyond
+ * `limit` within each domain). Exported for testing without fs.
+ *
+ * @param {Array<{file:string, domain:string, date:string}>} entries
+ * @param {number} limit
+ * @returns {Array<{file:string, domain:string, date:string}>} entries to remove
+ */
+function selectToPrune(entries, limit = DEFAULT_LIMIT) {
+  const byDomain = new Map();
+  for (const e of entries) {
+    const d = e.domain || "_undomained";
+    if (!byDomain.has(d)) byDomain.set(d, []);
+    byDomain.get(d).push(e);
+  }
+  const toPrune = [];
+  for (const list of byDomain.values()) {
+    // newest first (date desc, then filename desc for stable tie-break)
+    list.sort((a, b) =>
+      b.date !== a.date
+        ? b.date.localeCompare(a.date)
+        : b.file.localeCompare(a.file),
+    );
+    toPrune.push(...list.slice(limit));
+  }
+  return toPrune;
+}
+
+/** Minimal frontmatter `domain:` extractor (zero-dep). */
+function readDomain(content) {
+  const m = content.match(/^---\s*[\s\S]*?\bdomain:\s*["']?([^"'\n]+)["']?/m);
+  return m ? m[1].trim() : "";
+}
+
+async function run(_command, args, projectRoot) {
+  const dryRun = args.includes("--dry-run");
+  const limIdx = args.indexOf("--limit");
+  const limit =
+    limIdx >= 0 && args[limIdx + 1] ? parseInt(args[limIdx + 1], 10) : DEFAULT_LIMIT;
+
+  const dir = path.join(
+    projectRoot,
+    ".merlin-core",
+    "thoughts",
+    "shared",
+    "feedback",
+  );
+
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  } catch {
+    return { success: true, pruned: [], kept: 0, note: "no feedback directory" };
+  }
+
+  const entries = files.map((f) => {
+    const dateMatch = f.match(/^(\d{4}-\d{2}-\d{2})/);
+    let domain = "";
+    try {
+      domain = readDomain(fs.readFileSync(path.join(dir, f), "utf8"));
+    } catch {
+      /* unreadable → undomained */
+    }
+    return { file: f, domain, date: dateMatch ? dateMatch[1] : "0000-00-00" };
+  });
+
+  const toPrune = selectToPrune(entries, limit);
+
+  if (!dryRun) {
+    for (const e of toPrune) {
+      try {
+        fs.unlinkSync(path.join(dir, e.file));
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+
+  return {
+    success: true,
+    limit,
+    dryRun,
+    total: entries.length,
+    pruned: toPrune.map((e) => e.file),
+    kept: entries.length - toPrune.length,
+  };
+}
+
+function formatHuman(result) {
+  if (!result.success) return `FAILED: ${result.error}`;
+  const verb = result.dryRun ? "Would prune" : "Pruned";
+  return `${verb} ${result.pruned.length} feedback file(s); kept ${result.kept} (limit ${result.limit}/domain).`;
+}
+
+module.exports = { run, formatHuman, selectToPrune, DEFAULT_LIMIT };

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

@@ -0,0 +1,28 @@
+/**
+ * run-process -- Execute a certified PROCESSO locally (Constitution XIV).
+ *
+ * DRY-RUN by default (no commands executed) — also the rehearsal vehicle for the
+ * certification gates G3/G4. Pass --live to actually execute autonomous steps.
+ *
+ * Usage:
+ *   run-process <slug-or-path>            → dry-run (simulate decisions)
+ *   run-process <slug-or-path> --live     → execute autonomous steps start-to-stop
+ *
+ * @module tools/commands/run-process
+ */
+
+"use strict";
+
+const { runProcess } = require("../../core/process/executor");
+
+async function run(_command, args, projectRoot) {
+  const positionals = args.filter((a) => !a.startsWith("--"));
+  const fileOrSlug = positionals[0];
+  if (!fileOrSlug) {
+    throw new Error("Usage: run-process <slug-or-path> [--live]");
+  }
+  const dryRun = !args.includes("--live");
+  return runProcess(fileOrSlug, { dryRun, projectRoot });
+}
+
+module.exports = { run };

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

@@ -0,0 +1,79 @@
+/**
+ * state -- Read or write context bridge state
+ *
+ * Usage:
+ *   state              Dump entire bridge state
+ *   state <key>        Read specific key
+ *   state <key> <val>  Write key-value pair
+ *
+ * @module tools/commands/state
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function getBridgePath(projectRoot) {
+  return path.join(projectRoot, '.merlin', 'context-bridge.json');
+}
+
+function readBridge(projectRoot) {
+  const bridgePath = getBridgePath(projectRoot);
+  try {
+    return JSON.parse(fs.readFileSync(bridgePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeBridge(projectRoot, data) {
+  const bridgePath = getBridgePath(projectRoot);
+  const dir = path.dirname(bridgePath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(bridgePath, JSON.stringify(data, null, 2));
+}
+
+async function run(_command, args, projectRoot) {
+  if (args.length === 0) {
+    // Dump entire state
+    const state = readBridge(projectRoot);
+    if (!state) return { error: 'No bridge state found', path: getBridgePath(projectRoot) };
+    return state;
+  }
+
+  if (args.length === 1) {
+    // Read specific key
+    const state = readBridge(projectRoot);
+    if (!state) return { error: 'No bridge state found' };
+    const key = args[0];
+    return { key, value: state[key] !== undefined ? state[key] : null };
+  }
+
+  // Write key-value
+  const [key, rawValue] = args;
+  let value = rawValue;
+
+  // Auto-parse numbers and booleans
+  if (rawValue === 'true') value = true;
+  else if (rawValue === 'false') value = false;
+  else if (!isNaN(rawValue) && rawValue !== '') value = Number(rawValue);
+
+  const state = readBridge(projectRoot) || {};
+  state[key] = value;
+  writeBridge(projectRoot, state);
+
+  return { success: true, key, value };
+}
+
+function formatHuman(result) {
+  if (result.error) return `Error: ${result.error}`;
+  if (result.key !== undefined) {
+    return `${result.key} = ${JSON.stringify(result.value)}`;
+  }
+  return Object.entries(result)
+    .map(([k, v]) => `  ${k}: ${JSON.stringify(v)}`)
+    .join('\n');
+}
+
+module.exports = { run, formatHuman };

package/.merlin-core/tools/commands/sync-bridges.js

@@ -0,0 +1,197 @@
+/**
+ * sync-bridges — Regenerate .claude/commands/ bridge files from .merlin-core/commands/ sources.
+ *
+ * Each bridge file contains the FULL methodology from the Merlin command source,
+ * eliminating the 2-hop indirection problem. Claude Code gets complete instructions
+ * in a single file read.
+ *
+ * Usage:
+ *   node merlin-tools.js sync-bridges [--dry-run]
+ *
+ * @module tools/commands/sync-bridges
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Map from Merlin command source paths to .claude/commands/ bridge filenames.
+ * Keys are relative to .merlin-core/commands/, values are bridge filenames.
+ */
+const COMMAND_MAP = {
+  "research/research-codebase.md": "research.md",
+  "research/analyze-issue.md": "analyze-issue.md",
+  "planning/create-plan.md": "plan.md",
+  "planning/iterate-plan.md": "iterate-plan.md",
+  "planning/validate-plan.md": "validate-plan.md",
+  "implementation/implement-plan.md": "implement.md",
+  "implementation/oneshot.md": "oneshot.md",
+  "implementation/tdd.md": "tdd.md",
+  "git/commit.md": "commit.md",
+  "git/describe-pr.md": "describe-pr.md",
+  "session/fast-start.md": "fast-start.md",
+  "session/create-handoff.md": "handoff.md",
+  "session/resume-handoff.md": "resume-handoff.md",
+  "session/create-reminder.md": "create-reminder.md",
+  "session/create-objective.md": "create-objective.md",
+  "session/create-process.md": "create-process.md",
+  "session/check-objectives.md": "check-objectives.md",
+  "session/capture-learning.md": "capture-learning.md",
+  "session/capture-feedback.md": "capture-feedback.md",
+  "session/recall-learnings.md": "recall-learnings.md",
+  "session/recall-processes.md": "recall-processes.md",
+  "session/run-process.md": "run-process.md",
+  "session/conclude.md": "conclude.md",
+  "review/debug.md": "debug.md",
+  "review/doubts.md": "doubts.md",
+  "review/adversarial-review.md": "adversarial-review.md",
+  "review/verify-goals.md": "verify-goals.md",
+  "review/check.md": "check.md",
+  "review/local-review.md": "review.md",
+  "special/beauty.md": "beauty.md",
+  "special/elicit.md": "elicit.md",
+  "special/party.md": "party.md",
+  "special/common-ground.md": "common-ground.md",
+  "special/skill-audit.md": "skill-audit.md",
+  "special/start-here.md": "start-here.md",
+  "founder-mode.md": "founder-mode.md",
+};
+
+/**
+ * Bridge files that should NOT be overwritten (project-specific commands).
+ */
+const SKIP_LIST = ["converterparamagos.md"];
+
+/**
+ * Extract frontmatter fields from a Merlin command file.
+ * Returns { description, model, body }.
+ */
+function parseCommandFile(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)(?:\r?\n)?---\r?\n?/);
+  if (!match) return { description: "", model: null, body: content };
+
+  const raw = match[1];
+  const body = content.slice(match[0].length);
+
+  let description = "";
+  let model = null;
+
+  for (const line of raw.split(/\r?\n/)) {
+    const descMatch = line.match(/^description:\s*(.+)$/);
+    if (descMatch)
+      description = descMatch[1].trim().replace(/^['"]|['"]$/g, "");
+    const modelMatch = line.match(/^model:\s*(.+)$/);
+    if (modelMatch) model = modelMatch[1].trim();
+  }
+
+  return { description, model, body };
+}
+
+/**
+ * Generate a bridge file with the full command content embedded.
+ */
+function generateBridge(_bridgeName, _sourcePath, description, model, body) {
+  const lines = ["---"];
+  lines.push(`description: ${description}`);
+  if (model) lines.push(`model: ${model}`);
+  lines.push("---");
+  lines.push("");
+  lines.push(body.trimStart());
+
+  return lines.join("\n");
+}
+
+async function run(_command, args, projectRoot) {
+  const dryRun = args.includes("--dry-run");
+  const merlinCommandsDir = path.join(projectRoot, ".merlin-core", "commands");
+  const claudeCommandsDir = path.join(projectRoot, ".claude", "commands");
+
+  // Ensure .claude/commands/ exists
+  if (!dryRun && !fs.existsSync(claudeCommandsDir)) {
+    fs.mkdirSync(claudeCommandsDir, { recursive: true });
+  }
+
+  const results = {
+    generated: [],
+    skipped: [],
+    missing: [],
+    errors: [],
+    dryRun,
+  };
+
+  for (const [sourcePath, bridgeName] of Object.entries(COMMAND_MAP)) {
+    // Skip project-specific commands
+    if (SKIP_LIST.includes(bridgeName)) {
+      results.skipped.push({ bridge: bridgeName, reason: "in skip list" });
+      continue;
+    }
+
+    const sourceFile = path.join(merlinCommandsDir, sourcePath);
+    const bridgeFile = path.join(claudeCommandsDir, bridgeName);
+
+    if (!fs.existsSync(sourceFile)) {
+      results.missing.push({ source: sourcePath, bridge: bridgeName });
+      continue;
+    }
+
+    try {
+      const content = fs.readFileSync(sourceFile, "utf8");
+      const { description, model, body } = parseCommandFile(content);
+      const bridge = generateBridge(
+        bridgeName,
+        sourcePath,
+        description,
+        model,
+        body,
+      );
+
+      if (!dryRun) {
+        fs.writeFileSync(bridgeFile, bridge, "utf8");
+      }
+
+      results.generated.push({
+        bridge: bridgeName,
+        source: sourcePath,
+        model: model || "default",
+        size: bridge.length,
+      });
+    } catch (err) {
+      results.errors.push({
+        bridge: bridgeName,
+        source: sourcePath,
+        error: err.message,
+      });
+    }
+  }
+
+  return results;
+}
+
+function formatHuman(result) {
+  const lines = [];
+  const prefix = result.dryRun ? "[DRY RUN] " : "";
+
+  lines.push(
+    `${prefix}sync-bridges: ${result.generated.length} generated, ${result.skipped.length} skipped, ${result.missing.length} missing`,
+  );
+
+  for (const g of result.generated) {
+    lines.push(`  ✓ ${g.bridge} ← ${g.source} (${g.model}, ${g.size} bytes)`);
+  }
+  for (const s of result.skipped) {
+    lines.push(`  ⊘ ${s.bridge} — ${s.reason}`);
+  }
+  for (const m of result.missing) {
+    lines.push(`  ✗ ${m.bridge} — source not found: ${m.source}`);
+  }
+  for (const e of result.errors) {
+    lines.push(`  ✗ ${e.bridge} — ERROR: ${e.error}`);
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = { run, formatHuman, COMMAND_MAP, SKIP_LIST };