@caoscompanybr/merlin 3.5.0

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

@@ -0,0 +1,1135 @@
+/**
+ * Merlin-Tools: upgrade — Sync Merlin Core to a satellite project.
+ *
+ * Copies all framework files from the source of truth (this repo) to a target
+ * project, preserving project-specific data: thoughts, domain skills, and
+ * project-config.yaml.
+ *
+ * SAFETY: Uses copy-then-delete pattern (NEVER rename or delete-first).
+ * Temp backups are preserved on failure for manual recovery.
+ *
+ * Usage:
+ *   node .merlin-core/tools/merlin-tools.js upgrade <target-path> [--dry-run]
+ *
+ * Examples:
+ *   node .merlin-core/tools/merlin-tools.js upgrade "/path/to/project"
+ *   node .merlin-core/tools/merlin-tools.js upgrade "/path/to/another-project" --dry-run
+ *
+ * @module tools/commands/upgrade
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  copyDirSync,
+  rmDirSync,
+  countFiles,
+  listSubdirs,
+  countRealThoughts,
+  extractVersion,
+  extractFrameworkVersion,
+  extractProjectName,
+  bumpProjectConfigVersion,
+} = require("./lib/fs-safe");
+const { runPreflight } = require("./lib/preflight");
+const {
+  writeUpgradeReport,
+  formatWhatChanged,
+  formatRecoveryInstructions,
+} = require("./lib/report");
+const {
+  preserveProjectData,
+  restoreDomainSkills,
+  restoreThoughts,
+} = require("./lib/preserve");
+const { mergeSettingsLocal } = require("./lib/settings-merge");
+const syncBridges = require("./sync-bridges");
+
+// Directories that are part of the framework (synced on upgrade).
+// NOTE: "skills" and "thoughts" are handled separately — never list them here.
+const FRAMEWORK_DIRS = [
+  "core",
+  "commands",
+  "development",
+  "tools",
+  "data",
+  "elicitation",
+  "infrastructure",
+  "manifests",
+  "mcp-servers",
+  "monitor",
+  "presets",
+  "product",
+  "quality",
+  "schemas",
+  "scripts",
+  "utils",
+  "workflow-intelligence",
+  "hooks",
+];
+
+// Root-level framework files (synced on upgrade)
+const FRAMEWORK_FILES = [
+  "constitution.md",
+  "core-config.yaml",
+  "framework-config.yaml",
+  "index.js",
+  "local-config.yaml.template",
+];
+
+// Files in .claude/ to sync (overwrite from source)
+const CLAUDE_FILES = ["CLAUDE.md", "settings.json"];
+
+// Root-level project files to sync
+const PROJECT_ROOT_FILES = [".mcp.json"];
+
+async function run(command, args, projectRoot) {
+  // Flag parsing: filter out all known flags, leaving only positional targetPath.
+  // --yes is silently accepted (no-op in JS; needed for bash wrapper pass-through).
+  const dryRun = args.includes("--dry-run") || args.includes("-n");
+  const flattenNesting = args.includes("--flatten-nesting");
+  const knownFlags = new Set([
+    "--dry-run",
+    "-n",
+    "--yes",
+    "-y",
+    "--flatten-nesting",
+  ]);
+  const filteredArgs = args.filter((a) => !knownFlags.has(a));
+  const targetPath = filteredArgs[0];
+
+  if (!targetPath) {
+    throw new Error(
+      "Usage: upgrade <target-path> [--dry-run] [--yes] [--flatten-nesting]\n" +
+        'Example: upgrade "/path/to/project" --dry-run',
+    );
+  }
+
+  const resolvedTarget = path.resolve(targetPath);
+  const srcMerlin = path.join(projectRoot, ".merlin-core");
+  const dstMerlin = path.join(resolvedTarget, ".merlin-core");
+  const srcClaude = path.join(projectRoot, ".claude");
+  const dstClaude = path.join(resolvedTarget, ".claude");
+
+  // Validate source
+  if (!fs.existsSync(srcMerlin)) {
+    throw new Error(`Source .merlin-core not found at: ${srcMerlin}`);
+  }
+
+  // Validate target dir exists (even for CONVERSION mode, the project dir must exist)
+  if (!fs.existsSync(resolvedTarget)) {
+    throw new Error(`Target directory not found at: ${resolvedTarget}`);
+  }
+
+  // MODE DETECTION (Phase 5): no .merlin-core/ in target → CONVERSION; else → UPGRADE
+  const hasExistingMerlin = fs.existsSync(dstMerlin);
+  const mode = hasExistingMerlin ? "upgrade" : "convert";
+
+  // Read versions
+  // SOURCE: framework BUILD version from framework-config.yaml.framework_version
+  //   (NOT core-config.yaml.version — that's the schema version, doesn't bump
+  //    on releases. Reading the wrong file caused the pre-Phase-0 fleet drift
+  //    where the script thought everything was at 3.0.0 while source was 3.0.2.)
+  // TARGET: project's installed-framework version from project-config.yaml.version
+  //   (what THIS project thinks it's running — sed-bumped after each upgrade)
+  //   For CONVERSION mode: no project-config exists yet → "none"
+  const srcFrameworkConfig = path.join(srcMerlin, "framework-config.yaml");
+  const dstProjectConfigPath = path.join(dstMerlin, "project-config.yaml");
+  const srcVersion = extractFrameworkVersion(srcFrameworkConfig);
+  const dstVersion = hasExistingMerlin
+    ? extractVersion(dstProjectConfigPath)
+    : "none";
+
+  // Read project name: from existing config OR derive from dir name for CONVERSION
+  const dstProjectConfig = path.join(dstMerlin, "project-config.yaml");
+  const projectName = hasExistingMerlin
+    ? extractProjectName(dstProjectConfig)
+    : path.basename(resolvedTarget);
+
+  // Count project-owned data BEFORE upgrade (CONVERSION: zero of everything)
+  const dstThoughts = path.join(dstMerlin, "thoughts");
+  const dstDomain = path.join(dstMerlin, "skills", "domain");
+  const thoughtCount = hasExistingMerlin ? countRealThoughts(dstThoughts) : 0;
+  const domainSkills = hasExistingMerlin ? listSubdirs(dstDomain) : [];
+
+  const result = {
+    project: projectName,
+    target: resolvedTarget,
+    mode,
+    from: dstVersion,
+    to: srcVersion,
+    dryRun,
+    synced: { dirs: [], files: [], claude: [], rootFiles: [] },
+    preserved: {
+      projectConfig: hasExistingMerlin,
+      thoughts: thoughtCount,
+      domainSkills: domainSkills,
+    },
+    errors: [],
+  };
+
+  // ============================================================================
+  // PRE-FLIGHT — idempotency check, major-version warning, bug A + bug C scans
+  // ============================================================================
+  // Always runs FIRST. May short-circuit (idempotency) or print warnings.
+  // In dry-run mode, exits cleanly after the summary block.
+  const preflight = runPreflight({
+    projectDir: resolvedTarget,
+    projectName,
+    srcDir: projectRoot,
+    srcVersion,
+    currentVersion: dstVersion,
+    mode,
+    dryRun,
+    flattenNesting,
+    thoughtCount,
+    domainSkillCount: domainSkills.length,
+  });
+
+  // Capture preflight findings on result for downstream use + final report
+  result.preflight = {
+    brokenLinks: preflight.brokenLinks,
+    nestedSkills: preflight.nestedSkills,
+    willFlatten: preflight.willFlatten,
+  };
+
+  // Short-circuit: idempotency bail OR dry-run completion
+  if (preflight.shouldExit) {
+    result.shortCircuit = true;
+    result.shortCircuitReason =
+      dstVersion === srcVersion ? "idempotency" : "dry-run";
+    return result;
+  }
+
+  // ============================================================================
+  // CONVERSION BRANCH (Phase 5): target has no .merlin-core/ — fresh install
+  // ============================================================================
+  // CONVERSION skips preserve/restore (nothing to preserve) and does extra
+  // legacy cleanup: clears source's stale thoughts, migrates legacy thoughts/
+  // at project root, removes legacy .claude/agents and .claude/templates dirs,
+  // and generates a fresh project-config.yaml from the template.
+  if (mode === "convert") {
+    return runConversion({
+      resolvedTarget,
+      srcMerlin,
+      dstMerlin,
+      srcClaude,
+      dstClaude,
+      projectRoot,
+      projectName,
+      srcVersion,
+      result,
+    });
+  }
+
+  // === EXECUTE UPGRADE ===
+
+  // 1. Create pre-upgrade backup in .merlin-backups/latest/
+  const backupDir = path.join(resolvedTarget, ".merlin-backups", "latest");
+  try {
+    createPreUpgradeBackup(dstMerlin, dstClaude, backupDir, resolvedTarget);
+    result.backup = backupDir;
+  } catch (backupErr) {
+    result.errors.push(`Pre-upgrade backup warning: ${backupErr.message}`);
+    // Non-fatal: temp dir is the safety net
+  }
+
+  // 2. Backup project-config.yaml to memory
+  const projectConfigBackup = fs.readFileSync(dstProjectConfig, "utf8");
+
+  // 3. Preserve project-owned data: thoughts + domain skills
+  //    SAFE PATTERN: copy to temp, verify, then allow originals to be overwritten.
+  //    NEVER use renameSync (fails with EXDEV across drives on Windows).
+  const tempDir = path.join(
+    resolvedTarget,
+    `.merlin-upgrade-temp-${Date.now()}`,
+  );
+  fs.mkdirSync(tempDir, { recursive: true });
+
+  let upgradeVerified = false;
+
+  try {
+    // 3. Preserve project-owned data to temp (thoughts + domain skills + project-config).
+    //    Verifies thought-count integrity post-copy; throws ABORT if backup is incomplete.
+    preserveProjectData({
+      projectMerlinDir: dstMerlin,
+      tempDir,
+      thoughtCount,
+    });
+
+    // 4. Sync framework directories (delete + copy from source)
+    for (const dir of FRAMEWORK_DIRS) {
+      const src = path.join(srcMerlin, dir);
+      if (fs.existsSync(src)) {
+        const dst = path.join(dstMerlin, dir);
+        rmDirSync(dst);
+        const fileCount = copyDirSync(src, dst);
+        result.synced.dirs.push({ name: dir, files: fileCount });
+      }
+    }
+
+    // 5. Sync skills/general (replace entirely)
+    const srcGeneral = path.join(srcMerlin, "skills", "general");
+    const dstGeneral = path.join(dstMerlin, "skills", "general");
+    if (fs.existsSync(srcGeneral)) {
+      rmDirSync(dstGeneral);
+      const fileCount = copyDirSync(srcGeneral, dstGeneral);
+      result.synced.dirs.push({ name: "skills/general", files: fileCount });
+    }
+
+    // 6. Restore domain skills (BUG B + bug C defenses live in preserve module).
+    //    - rm -rf target before cp -r per skill (bug B — project wins on conflict)
+    //    - opt-in flatten of legacy nested subdirs (bug C — via preflight willFlatten)
+    //    - additive merge of source-only skills (new from framework)
+    const domainResult = restoreDomainSkills({
+      tempDomainDir: path.join(tempDir, "domain"),
+      dstDomainDir: path.join(dstMerlin, "skills", "domain"),
+      srcDomainDir: path.join(srcMerlin, "skills", "domain"),
+      flattenNesting: preflight.willFlatten,
+      nestedSkills: preflight.nestedSkills,
+    });
+    if (domainResult.addedFromSource.length > 0) {
+      result.synced.dirs.push({
+        name: `skills/domain (added: ${domainResult.addedFromSource.join(", ")})`,
+        files: domainResult.addedFromSource.length,
+      });
+    }
+    if (domainResult.flattened.length > 0) {
+      result.synced.dirs.push({
+        name: `skills/domain (flattened legacy nesting: ${domainResult.flattened.join(", ")})`,
+        files: domainResult.flattened.length,
+      });
+    }
+
+    // 7. Restore thoughts from temp (wholesale replace; ensure canonical subdirs;
+    //    throw ABORT if count regresses).
+    restoreThoughts({
+      tempThoughtsDir: path.join(tempDir, "thoughts"),
+      dstThoughtsDir: path.join(dstMerlin, "thoughts"),
+      thoughtCountBefore: thoughtCount,
+    });
+
+    upgradeVerified = true;
+  } finally {
+    // SAFETY: Only delete temp if upgrade verified successfully.
+    // If not verified, preserve temp for manual recovery.
+    if (upgradeVerified) {
+      rmDirSync(tempDir);
+    } else {
+      result.errors.push(
+        `Temp backup preserved at ${tempDir} — upgrade not fully verified. ` +
+          `Restore from there or from .merlin-backups/latest/ if needed.`,
+      );
+    }
+  }
+
+  // 8. Sync framework root files
+  for (const file of FRAMEWORK_FILES) {
+    const src = path.join(srcMerlin, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(dstMerlin, file));
+      result.synced.files.push(file);
+    }
+  }
+
+  // 9. Restore project-config.yaml (preserve project identity)
+  fs.writeFileSync(dstProjectConfig, projectConfigBackup, "utf8");
+
+  // 9a. Bump version in project-config.yaml to match source
+  bumpProjectConfigVersion(dstProjectConfig, srcVersion);
+
+  // 10. Sync .claude/rules (additive — never delete first)
+  fs.mkdirSync(dstClaude, { recursive: true });
+  const srcRules = path.join(srcClaude, "rules");
+  if (fs.existsSync(srcRules)) {
+    const dstRules = path.join(dstClaude, "rules");
+    fs.mkdirSync(dstRules, { recursive: true });
+    const fileCount = copyDirSync(srcRules, dstRules);
+    result.synced.claude.push({ name: ".claude/rules", files: fileCount });
+  }
+
+  // 10a. Regenerate .claude/commands/ bridges via sync-bridges (Phase 6).
+  //      Replaces the prior "copy .claude/commands/ wholesale" — bridges
+  //      are now properly generated from .merlin-core/commands/ sources
+  //      so the target has the same 31 enriched bridges as gestao-merlin.
+  try {
+    const bridgesResult = await syncBridges.run(
+      "sync-bridges",
+      [],
+      resolvedTarget,
+    );
+    if (bridgesResult && bridgesResult.generated) {
+      result.synced.claude.push({
+        name: ".claude/commands (sync-bridges)",
+        files: bridgesResult.generated.length,
+      });
+    }
+  } catch (bridgeErr) {
+    result.errors.push(`sync-bridges failed: ${bridgeErr.message}`);
+  }
+
+  // 10b. Copy converterparamagos.md (project-specific — not generated by sync-bridges)
+  const converterSrc = path.join(
+    srcClaude,
+    "commands",
+    "converterparamagos.md",
+  );
+  if (fs.existsSync(converterSrc)) {
+    const dstCommands = path.join(dstClaude, "commands");
+    fs.mkdirSync(dstCommands, { recursive: true });
+    fs.copyFileSync(
+      converterSrc,
+      path.join(dstCommands, "converterparamagos.md"),
+    );
+  }
+
+  // 10c. Copy .claude/commands/Merlin/ subfolder if present (agents, commands, skills bridges)
+  const merlinSubfolderSrc = path.join(srcClaude, "commands", "Merlin");
+  if (fs.existsSync(merlinSubfolderSrc)) {
+    const merlinSubfolderDst = path.join(dstClaude, "commands", "Merlin");
+    const fileCount = copyDirSync(merlinSubfolderSrc, merlinSubfolderDst);
+    result.synced.claude.push({
+      name: ".claude/commands/Merlin",
+      files: fileCount,
+    });
+  }
+
+  // 11. Sync .claude/CLAUDE.md + .claude/settings.json (hard-overwrite is fine — framework-owned)
+  for (const file of CLAUDE_FILES) {
+    const src = path.join(srcClaude, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(dstClaude, file));
+      result.synced.claude.push({ name: `.claude/${file}`, files: 1 });
+    }
+  }
+
+  // 11a. Sync .claude/hooks/*.js (additive — copy each file individually)
+  const srcHooks = path.join(srcClaude, "hooks");
+  if (fs.existsSync(srcHooks)) {
+    const dstHooks = path.join(dstClaude, "hooks");
+    fs.mkdirSync(dstHooks, { recursive: true });
+    let hookCount = 0;
+    for (const entry of fs.readdirSync(srcHooks, { withFileTypes: true })) {
+      if (
+        entry.isFile() &&
+        (entry.name.endsWith(".js") || entry.name.endsWith(".cjs"))
+      ) {
+        fs.copyFileSync(
+          path.join(srcHooks, entry.name),
+          path.join(dstHooks, entry.name),
+        );
+        hookCount++;
+      }
+    }
+    if (hookCount > 0) {
+      result.synced.claude.push({ name: ".claude/hooks", files: hookCount });
+    }
+  }
+
+  // 11a-bis. Wire the license gate into the target's settings.json (customer
+  //          installs only — the framework's own settings omits it on purpose).
+  ensureLicenseGateRegistered(dstClaude, result);
+
+  // 11b. INTELLIGENT MERGE of .claude/settings.local.json (Phase 6).
+  //      Preserves operator's permissions; additively merges source's hook
+  //      registrations with dedupe-by-command. Non-fatal on errors.
+  try {
+    const srcSettings = path.join(srcClaude, "settings.local.json");
+    if (fs.existsSync(srcSettings)) {
+      const mergeResult = mergeSettingsLocal({
+        srcSettingsPath: srcSettings,
+        dstSettingsPath: path.join(dstClaude, "settings.local.json"),
+      });
+      if (mergeResult.created || mergeResult.merged) {
+        result.synced.claude.push({
+          name: ".claude/settings.local.json (merged)",
+          files: 1,
+        });
+      }
+    }
+  } catch (mergeErr) {
+    result.errors.push(`settings.local.json merge failed: ${mergeErr.message}`);
+  }
+
+  // 12. Sync project root files (.mcp.json)
+  for (const file of PROJECT_ROOT_FILES) {
+    const src = path.join(projectRoot, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(resolvedTarget, file));
+      result.synced.rootFiles.push(file);
+    }
+  }
+
+  // 13. Final verification
+  // Post-upgrade: read from project-config.yaml (sed-bumped to srcVersion in step 9a)
+  const finalVersion = extractVersion(
+    path.join(dstMerlin, "project-config.yaml"),
+  );
+  const finalThoughts = countRealThoughts(path.join(dstMerlin, "thoughts"));
+  const finalDomainSkills = listSubdirs(dstDomain);
+  const finalAgents = countFiles(path.join(dstMerlin, "development", "agents"));
+  // Count .md files at .claude/commands/ top level (not subdirs)
+  const claudeCommandsDir = path.join(resolvedTarget, ".claude", "commands");
+  let finalCommandCount = 0;
+  if (fs.existsSync(claudeCommandsDir)) {
+    finalCommandCount = fs
+      .readdirSync(claudeCommandsDir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith(".md")).length;
+  }
+
+  result.verified = finalVersion === srcVersion;
+  result.preserved.thoughtsAfter = finalThoughts;
+  result.preserved.domainSkillsAfter = finalDomainSkills.length;
+  result.installed = { agents: finalAgents, commands: finalCommandCount };
+
+  // 14. Write upgrade-report.json (always, even on partial failure)
+  const reportDate = new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\..*$/, "")
+    .replace("T", "-");
+  const reportPath = writeUpgradeReport({
+    targetDir: resolvedTarget,
+    projectName,
+    projectDir: resolvedTarget,
+    merlinSource: projectRoot,
+    date: reportDate,
+    mode: "upgrade",
+    versionFrom: dstVersion,
+    versionTo: srcVersion,
+    preserved: {
+      thoughts_before: thoughtCount,
+      thoughts_after: finalThoughts,
+      domain_skills_before: domainSkills.length,
+      domain_skills_after: finalDomainSkills.length,
+    },
+    installed: {
+      agents: finalAgents,
+      commands: finalCommandCount,
+    },
+    backups: {
+      claude_backup: "", // JS engine doesn't snapshot full .claude — only .claude/commands
+      merlin_core_backup: result.backup || "",
+    },
+    errors: result.errors.length,
+    verified: result.verified,
+  });
+  if (reportPath) {
+    result.reportPath = reportPath;
+  }
+
+  // 15. Print WHAT CHANGED block (success) or recovery instructions (failure)
+  if (result.verified && result.errors.length === 0) {
+    console.log(
+      formatWhatChanged({
+        versionFrom: dstVersion,
+        versionTo: srcVersion,
+        thoughtsBefore: thoughtCount,
+        thoughtsAfter: finalThoughts,
+        domainBefore: domainSkills.length,
+        domainAfter: finalDomainSkills.length,
+        agentsCount: finalAgents,
+        commandsCount: finalCommandCount,
+      }),
+    );
+  } else {
+    console.log(
+      formatRecoveryInstructions({
+        projectDir: resolvedTarget,
+        merlinSource: projectRoot,
+        backupDir:
+          result.backup ||
+          path.join(resolvedTarget, ".merlin-backups", "latest"),
+        scriptPath: path.join(
+          projectRoot,
+          ".merlin-core",
+          "tools",
+          "merlin-tools.js",
+        ),
+      }),
+    );
+  }
+
+  return result;
+}
+
+/**
+ * CONVERSION pipeline: target has no .merlin-core/ — fresh install + legacy cleanup.
+ *
+ * Differs from UPGRADE in 4 ways:
+ *   - No preserve step (nothing to preserve in target)
+ *   - No restoreDomainSkills / restoreThoughts (source's content stays as-is then trimmed)
+ *   - Cleans source's stale thoughts/shared/* (those belong to framework, not new project)
+ *   - Migrates legacy thoughts/ from project root into .merlin-core/thoughts/shared/
+ *   - Removes legacy .claude/agents/ and .claude/templates/ dirs
+ *   - Generates fresh project-config.yaml from template (with {{PROJECT_NAME}}, {{SOURCE_VERSION}})
+ */
+function runConversion(opts) {
+  const {
+    resolvedTarget,
+    srcMerlin,
+    dstMerlin,
+    srcClaude,
+    dstClaude,
+    projectRoot,
+    projectName,
+    srcVersion,
+    result,
+  } = opts;
+
+  // 1. Copy fresh .merlin-core/ from source (whole tree)
+  fs.mkdirSync(dstMerlin, { recursive: true });
+  for (const dir of FRAMEWORK_DIRS) {
+    const src = path.join(srcMerlin, dir);
+    if (fs.existsSync(src)) {
+      const dst = path.join(dstMerlin, dir);
+      const fileCount = copyDirSync(src, dst);
+      result.synced.dirs.push({ name: dir, files: fileCount });
+    }
+  }
+  // skills/ (general + domain — both fresh from source for CONVERSION)
+  const srcSkills = path.join(srcMerlin, "skills");
+  if (fs.existsSync(srcSkills)) {
+    const fileCount = copyDirSync(srcSkills, path.join(dstMerlin, "skills"));
+    result.synced.dirs.push({ name: "skills", files: fileCount });
+  }
+  // framework root files
+  for (const file of FRAMEWORK_FILES) {
+    const src = path.join(srcMerlin, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(dstMerlin, file));
+      result.synced.files.push(file);
+    }
+  }
+
+  // 2. Clean source's stale thoughts/shared/* (framework's, not project's)
+  const dstThoughtsShared = path.join(dstMerlin, "thoughts", "shared");
+  const THOUGHT_SUBDIRS = [
+    "decisions",
+    "handoffs",
+    "learnings",
+    "objectives",
+    "plans",
+    "processes",
+    "reminders",
+    "research",
+    "feedback",
+  ];
+  for (const sub of THOUGHT_SUBDIRS) {
+    const dir = path.join(dstThoughtsShared, sub);
+    rmDirSync(dir);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, ".gitkeep"), "");
+  }
+  // Also clean root-level INDEX files (will be regenerated)
+  for (const f of ["INDEX.json", "INDEX.md"]) {
+    const p = path.join(dstThoughtsShared, f);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  }
+
+  // 3. Migrate legacy thoughts/ at project root into .merlin-core/thoughts/shared/
+  const legacyThoughts = path.join(resolvedTarget, "thoughts");
+  let migrated = 0;
+  if (fs.existsSync(legacyThoughts)) {
+    const legacyShared = path.join(legacyThoughts, "shared");
+    if (fs.existsSync(legacyShared)) {
+      for (const sub of THOUGHT_SUBDIRS) {
+        const srcSubdir = path.join(legacyShared, sub);
+        if (!fs.existsSync(srcSubdir)) continue;
+        const dstSubdir = path.join(dstThoughtsShared, sub);
+        for (const entry of fs.readdirSync(srcSubdir, {
+          withFileTypes: true,
+        })) {
+          if (entry.isFile() && entry.name !== ".gitkeep") {
+            fs.copyFileSync(
+              path.join(srcSubdir, entry.name),
+              path.join(dstSubdir, entry.name),
+            );
+            migrated++;
+          }
+        }
+      }
+    }
+  }
+  if (migrated > 0) {
+    result.migratedLegacyThoughts = migrated;
+    result.legacyThoughtsRootPreserved = legacyThoughts;
+  }
+
+  // 4. Remove legacy .claude/agents/ and .claude/templates/ if present
+  const legacyAgents = path.join(dstClaude, "agents");
+  const legacyTemplates = path.join(dstClaude, "templates");
+  if (fs.existsSync(legacyAgents)) {
+    rmDirSync(legacyAgents);
+    result.removedLegacy = (result.removedLegacy || []).concat([
+      ".claude/agents",
+    ]);
+  }
+  if (fs.existsSync(legacyTemplates)) {
+    rmDirSync(legacyTemplates);
+    result.removedLegacy = (result.removedLegacy || []).concat([
+      ".claude/templates",
+    ]);
+  }
+
+  // 4b. Bug-D defense — back up pre-existing .claude/* + .mcp.json BEFORE
+  //     Step 5/6 overwrites them. Delegated to shared helper so UPGRADE mode
+  //     uses the same code path.
+  //     See: learnings/2026-05-17-plan-a-conversion-doesnt-backup-claude-mcp.md
+  const convertBackupDir = path.join(
+    resolvedTarget,
+    ".merlin-backups",
+    "latest",
+  );
+  backupOverwriteRiskArtifacts(dstClaude, resolvedTarget, convertBackupDir);
+
+  // 5. Sync .claude/ (rules + sync-bridges-generated commands + Merlin/ subfolder +
+  //    converterparamagos + CLAUDE.md + settings.json + hooks + settings.local.json merge)
+  fs.mkdirSync(dstClaude, { recursive: true });
+  const srcRules = path.join(srcClaude, "rules");
+  if (fs.existsSync(srcRules)) {
+    const dstRules = path.join(dstClaude, "rules");
+    fs.mkdirSync(dstRules, { recursive: true });
+    const fileCount = copyDirSync(srcRules, dstRules);
+    result.synced.claude.push({ name: ".claude/rules", files: fileCount });
+  }
+  // Bridges generated from .merlin-core/commands/ sources
+  // (caller-async note: runConversion is sync but syncBridges.run is async-but-sync-body;
+  //  we treat it as sync via .then-style would complicate — but the run() function is
+  //  marked async so callers await; bridges only does fs ops; calling without await is fine
+  //  in practice since its work completes synchronously before any returned promise resolves.
+  //  Doing a fire-and-forget here mirrors how the test fixture handles it.)
+  try {
+    const bridgesResult = syncBridges.run("sync-bridges", [], resolvedTarget);
+    // syncBridges.run() returns the result object directly (despite being async,
+    // its body is sync; the Promise just wraps the result).
+    if (bridgesResult && typeof bridgesResult.then === "function") {
+      // Best-effort: don't block — but in CONVERSION we want bridges before we return.
+      // Switch to await would require runConversion to be async — change deferred.
+    }
+  } catch (bridgeErr) {
+    result.errors.push(`sync-bridges failed: ${bridgeErr.message}`);
+  }
+  // converterparamagos.md (project-specific)
+  const converterSrc = path.join(
+    srcClaude,
+    "commands",
+    "converterparamagos.md",
+  );
+  if (fs.existsSync(converterSrc)) {
+    const dstCommands = path.join(dstClaude, "commands");
+    fs.mkdirSync(dstCommands, { recursive: true });
+    fs.copyFileSync(
+      converterSrc,
+      path.join(dstCommands, "converterparamagos.md"),
+    );
+  }
+  // .claude/commands/Merlin/ subfolder
+  const merlinSubfolderSrc = path.join(srcClaude, "commands", "Merlin");
+  if (fs.existsSync(merlinSubfolderSrc)) {
+    copyDirSync(merlinSubfolderSrc, path.join(dstClaude, "commands", "Merlin"));
+  }
+  // CLAUDE.md + settings.json
+  for (const file of CLAUDE_FILES) {
+    const src = path.join(srcClaude, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(dstClaude, file));
+      result.synced.claude.push({ name: `.claude/${file}`, files: 1 });
+    }
+  }
+  // .claude/hooks/*.js
+  const srcHooks = path.join(srcClaude, "hooks");
+  if (fs.existsSync(srcHooks)) {
+    const dstHooks = path.join(dstClaude, "hooks");
+    fs.mkdirSync(dstHooks, { recursive: true });
+    for (const entry of fs.readdirSync(srcHooks, { withFileTypes: true })) {
+      if (
+        entry.isFile() &&
+        (entry.name.endsWith(".js") || entry.name.endsWith(".cjs"))
+      ) {
+        fs.copyFileSync(
+          path.join(srcHooks, entry.name),
+          path.join(dstHooks, entry.name),
+        );
+      }
+    }
+  }
+  // Wire the license gate into the target's settings.json (customer install).
+  ensureLicenseGateRegistered(dstClaude, result);
+  // settings.local.json merge
+  try {
+    const srcSettings = path.join(srcClaude, "settings.local.json");
+    if (fs.existsSync(srcSettings)) {
+      mergeSettingsLocal({
+        srcSettingsPath: srcSettings,
+        dstSettingsPath: path.join(dstClaude, "settings.local.json"),
+      });
+    }
+  } catch (mergeErr) {
+    result.errors.push(`settings.local.json merge failed: ${mergeErr.message}`);
+  }
+
+  // 6. Sync .mcp.json
+  for (const file of PROJECT_ROOT_FILES) {
+    const src = path.join(projectRoot, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(resolvedTarget, file));
+      result.synced.rootFiles.push(file);
+    }
+  }
+
+  // 7. Generate project-config.yaml from template
+  const templatePath = path.join(
+    __dirname,
+    "lib",
+    "project-config.template.yaml",
+  );
+  if (fs.existsSync(templatePath)) {
+    let template = fs.readFileSync(templatePath, "utf8");
+    template = template
+      .replace(/\{\{PROJECT_NAME\}\}/g, projectName)
+      .replace(/\{\{SOURCE_VERSION\}\}/g, srcVersion);
+    fs.writeFileSync(
+      path.join(dstMerlin, "project-config.yaml"),
+      template,
+      "utf8",
+    );
+    result.generatedProjectConfig = true;
+  } else {
+    result.errors.push(
+      `project-config.template.yaml not found at: ${templatePath}`,
+    );
+  }
+
+  // 8. Verification (lighter than UPGRADE — only check key files exist)
+  const finalAgents = countFiles(path.join(dstMerlin, "development", "agents"));
+  const claudeCommandsDir = path.join(resolvedTarget, ".claude", "commands");
+  let finalCommandCount = 0;
+  if (fs.existsSync(claudeCommandsDir)) {
+    finalCommandCount = fs
+      .readdirSync(claudeCommandsDir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith(".md")).length;
+  }
+  const finalDomainSkills = listSubdirs(
+    path.join(dstMerlin, "skills", "domain"),
+  );
+  result.verified =
+    fs.existsSync(path.join(dstMerlin, "constitution.md")) &&
+    fs.existsSync(path.join(dstMerlin, "project-config.yaml")) &&
+    finalAgents >= 15;
+  result.preserved.thoughtsAfter = countRealThoughts(
+    path.join(dstMerlin, "thoughts"),
+  );
+  result.preserved.domainSkillsAfter = finalDomainSkills.length;
+  result.installed = { agents: finalAgents, commands: finalCommandCount };
+
+  // 9. Write upgrade-report.json (CONVERSION variant)
+  const reportDate = new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\..*$/, "")
+    .replace("T", "-");
+  const reportPath = writeUpgradeReport({
+    targetDir: resolvedTarget,
+    projectName,
+    projectDir: resolvedTarget,
+    merlinSource: projectRoot,
+    date: reportDate,
+    mode: "convert",
+    versionFrom: "none",
+    versionTo: srcVersion,
+    preserved: {
+      thoughts_before: 0,
+      thoughts_after: result.preserved.thoughtsAfter,
+      domain_skills_before: 0,
+      domain_skills_after: result.preserved.domainSkillsAfter,
+    },
+    installed: { agents: finalAgents, commands: finalCommandCount },
+    backups: { claude_backup: "", merlin_core_backup: "" },
+    errors: result.errors.length,
+    verified: result.verified,
+  });
+  if (reportPath) result.reportPath = reportPath;
+
+  // 10. WHAT CHANGED (success) or recovery (failure)
+  if (result.verified && result.errors.length === 0) {
+    console.log(
+      formatWhatChanged({
+        versionFrom: "none",
+        versionTo: srcVersion,
+        thoughtsBefore: 0,
+        thoughtsAfter: result.preserved.thoughtsAfter,
+        domainBefore: 0,
+        domainAfter: result.preserved.domainSkillsAfter,
+        agentsCount: finalAgents,
+        commandsCount: finalCommandCount,
+      }),
+    );
+  } else {
+    console.log(
+      formatRecoveryInstructions({
+        projectDir: resolvedTarget,
+        merlinSource: projectRoot,
+        backupDir: path.join(resolvedTarget, ".merlin-backups", "latest"),
+        scriptPath: path.join(
+          projectRoot,
+          ".merlin-core",
+          "tools",
+          "merlin-tools.js",
+        ),
+      }),
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Pure: should the license gate be wired for THIS install? Opt-in only — the
+ * paid-client install sets `MERLIN_LICENSE_GATE=1`. Every other install (and the
+ * dev repo) leaves it unset, so we do NOT auto-inject a blocking hook that would
+ * brick an unlicensed session (see .claude/hooks/README-license-gate.md and
+ * [[gotcha-merlin-license-gate-blocks-fresh-install]]).
+ */
+function shouldRegisterLicenseGate(env = process.env) {
+  return env.MERLIN_LICENSE_GATE === "1";
+}
+
+/**
+ * Pure: given a parsed settings object, return a NEW settings object with the
+ * license-gate hook registered AND the arming env (`env.MERLIN_LICENSE_GATE="1"`)
+ * set so the hook is live at runtime — or null if it was already wired
+ * (idempotent). Does no I/O.
+ */
+function computeLicenseGateSettings(settings) {
+  const existing = (settings.hooks && settings.hooks.UserPromptSubmit) || [];
+  if (JSON.stringify(existing).includes("license-gate.cjs")) return null;
+  return {
+    ...settings,
+    hooks: {
+      ...(settings.hooks || {}),
+      UserPromptSubmit: [
+        ...existing,
+        {
+          hooks: [
+            { type: "command", command: "node .claude/hooks/license-gate.cjs" },
+          ],
+        },
+      ],
+    },
+    env: { ...(settings.env || {}), MERLIN_LICENSE_GATE: "1" },
+  };
+}
+
+/**
+ * Register + ARM the license gate in the TARGET project's settings.json — but
+ * only for an opted-in (paid-client) install. The hook ships either way; this
+ * just wires it and sets the arming env. Idempotent + non-fatal.
+ */
+function ensureLicenseGateRegistered(dstClaude, result, opts = {}) {
+  try {
+    if (!shouldRegisterLicenseGate(opts.env || process.env)) return; // opt-in only
+    const settingsPath = path.join(dstClaude, "settings.json");
+    if (!fs.existsSync(settingsPath)) return;
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    const next = computeLicenseGateSettings(settings);
+    if (!next) return; // already wired
+    fs.writeFileSync(settingsPath, JSON.stringify(next, null, 2) + "\n");
+    result.synced.claude.push({
+      name: ".claude/settings.json (license gate, armed)",
+      files: 1,
+    });
+  } catch {
+    // non-fatal — never let a settings.json quirk break the install
+  }
+}
+
+/**
+ * Bug-D defense — back up files that the install/upgrade pipeline overwrites:
+ *   .claude/CLAUDE.md, .claude/settings.json, .claude/hooks/, .mcp.json
+ * .claude/rules/ is intentionally excluded — its sync is additive.
+ * Idempotent: missing source files are silently skipped.
+ *
+ * Used by BOTH:
+ *   - runConversion()'s Step 4b (before .claude/ + .mcp.json overwrites)
+ *   - createPreUpgradeBackup() (UPGRADE mode parity)
+ *
+ * @param {string} claudeDir   Target's .claude/ directory
+ * @param {string} mcpRoot     Target's root (for .mcp.json)
+ * @param {string} backupDir   Destination .merlin-backups/latest/
+ */
+function backupOverwriteRiskArtifacts(claudeDir, mcpRoot, backupDir) {
+  fs.mkdirSync(backupDir, { recursive: true });
+  const backupClaudeDir = path.join(backupDir, ".claude");
+  const claudeMd = path.join(claudeDir, "CLAUDE.md");
+  if (fs.existsSync(claudeMd)) {
+    fs.mkdirSync(backupClaudeDir, { recursive: true });
+    fs.copyFileSync(claudeMd, path.join(backupClaudeDir, "CLAUDE.md"));
+  }
+  const claudeSettings = path.join(claudeDir, "settings.json");
+  if (fs.existsSync(claudeSettings)) {
+    fs.mkdirSync(backupClaudeDir, { recursive: true });
+    fs.copyFileSync(
+      claudeSettings,
+      path.join(backupClaudeDir, "settings.json"),
+    );
+  }
+  const claudeHooks = path.join(claudeDir, "hooks");
+  if (fs.existsSync(claudeHooks)) {
+    copyDirSync(claudeHooks, path.join(backupClaudeDir, "hooks"));
+  }
+  const mcpJson = path.join(mcpRoot, ".mcp.json");
+  if (fs.existsSync(mcpJson)) {
+    fs.copyFileSync(mcpJson, path.join(backupDir, ".mcp.json"));
+  }
+}
+
+/**
+ * Create a pre-upgrade backup in .merlin-backups/latest/.
+ * Rotates old backup (only keeps one).
+ */
+function createPreUpgradeBackup(merlinDir, claudeDir, backupDir, targetRoot) {
+  // Rotate: delete previous "latest" if exists
+  rmDirSync(backupDir);
+  fs.mkdirSync(backupDir, { recursive: true });
+
+  // Backup thoughts
+  const srcThoughts = path.join(merlinDir, "thoughts");
+  if (fs.existsSync(srcThoughts)) {
+    copyDirSync(srcThoughts, path.join(backupDir, "thoughts"));
+  }
+
+  // Backup domain skills
+  const srcDomain = path.join(merlinDir, "skills", "domain");
+  if (fs.existsSync(srcDomain)) {
+    copyDirSync(srcDomain, path.join(backupDir, "domain-skills"));
+  }
+
+  // Backup project-config
+  const projConfig = path.join(merlinDir, "project-config.yaml");
+  if (fs.existsSync(projConfig)) {
+    fs.copyFileSync(projConfig, path.join(backupDir, "project-config.yaml"));
+  }
+
+  // Backup .claude/commands (custom satellite commands)
+  const claudeCommands = path.join(claudeDir, "commands");
+  if (fs.existsSync(claudeCommands)) {
+    copyDirSync(claudeCommands, path.join(backupDir, "claude-commands"));
+  }
+
+  // Bug-D parity (2026-05-17) — delegate to shared helper so CONVERT mode
+  // also gets the same coverage. Falls back to deriving targetRoot from
+  // claudeDir when not passed (backward-compat for older call sites).
+  backupOverwriteRiskArtifacts(
+    claudeDir,
+    targetRoot || path.dirname(claudeDir),
+    backupDir,
+  );
+
+  // Write manifest — version is project's pre-upgrade installed version
+  const manifest = {
+    timestamp: new Date().toISOString(),
+    version: extractVersion(path.join(merlinDir, "project-config.yaml")),
+    contents: [
+      "thoughts",
+      "domain-skills",
+      "project-config.yaml",
+      "claude-commands",
+      ".claude/CLAUDE.md",
+      ".claude/settings.json",
+      ".claude/hooks",
+      ".mcp.json",
+    ],
+  };
+  fs.writeFileSync(
+    path.join(backupDir, "backup-manifest.json"),
+    JSON.stringify(manifest, null, 2),
+  );
+}
+
+function formatHuman(result) {
+  // Short-circuit cases (idempotency bail OR dry-run): preflight already printed
+  // the banner + summary live during execution. Nothing more to add here.
+  if (result.shortCircuit) {
+    return result.reportPath ? `\nReport written: ${result.reportPath}\n` : "";
+  }
+
+  const lines = [];
+  const mode = result.dryRun ? "DRY RUN" : "UPGRADE";
+  lines.push(`\n=== Merlin Core ${mode}: ${result.project} ===`);
+  lines.push(`Target:  ${result.target}`);
+  lines.push(`Version: ${result.from} → ${result.to}`);
+  lines.push("");
+
+  if (result.backup) {
+    lines.push(`Pre-upgrade backup: ${result.backup}`);
+    lines.push("");
+  }
+
+  if (result.synced.dirs.length > 0) {
+    lines.push("Framework directories:");
+    for (const d of result.synced.dirs) {
+      lines.push(`  ✓ ${d.name} (${d.files} files)`);
+    }
+  }
+
+  if (result.synced.files.length > 0) {
+    lines.push("\nFramework files:");
+    for (const f of result.synced.files) {
+      lines.push(`  ✓ ${f}`);
+    }
+  }
+
+  if (result.synced.claude.length > 0) {
+    lines.push("\nClaude IDE integration:");
+    for (const c of result.synced.claude) {
+      lines.push(`  ✓ ${c.name} (${c.files} files)`);
+    }
+  }
+
+  if (result.synced.rootFiles && result.synced.rootFiles.length > 0) {
+    lines.push("\nProject root files:");
+    for (const f of result.synced.rootFiles) {
+      lines.push(`  ✓ ${f}`);
+    }
+  }
+
+  // Preserved data
+  const p = result.preserved;
+  lines.push("\nPreserved (project-owned):");
+  lines.push(`  ✓ project-config.yaml`);
+  lines.push(
+    `  ✓ thoughts/ (${p.thoughts} files${p.thoughtsAfter !== undefined ? ` → ${p.thoughtsAfter} after` : ""})`,
+  );
+  lines.push(
+    `  ✓ skills/domain/ (${p.domainSkills.length} skills: ${p.domainSkills.join(", ") || "none"})`,
+  );
+
+  if (!result.dryRun && result.verified !== undefined) {
+    lines.push(
+      `\nVerification: ${result.verified ? "PASSED" : "FAILED"} (${result.to})`,
+    );
+  }
+
+  if (result.errors.length > 0) {
+    lines.push("\nWarnings:");
+    for (const e of result.errors) {
+      lines.push(`  ⚠ ${e}`);
+    }
+  }
+
+  if (result.reportPath) {
+    lines.push(`\nReport written: ${result.reportPath}`);
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  run,
+  formatHuman,
+  shouldRegisterLicenseGate,
+  computeLicenseGateSettings,
+};