@nolto/cli 0.8.0 → 0.9.0

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { createRequire as createRequire3 } from "module";
 import { fileURLToPath as fileURLToPath4 } from "url";
-import path15 from "path";
+import path19 from "path";
 import { CommanderError } from "commander";
 
 // src/config.ts
@@ -314,11 +314,11 @@ function maskToken(token) {
 function createHttpClient(opts) {
   const { baseUrl, version, token } = opts;
   const base = baseUrl.replace(/\/+$/, "");
-  async function request(method, path16, body) {
-    if (!path16.startsWith("/api/")) {
-      throw new CliError(`HTTP client path must start with /api/, got: ${path16}`, 2);
+  async function request(method, path20, body) {
+    if (!path20.startsWith("/api/")) {
+      throw new CliError(`HTTP client path must start with /api/, got: ${path20}`, 2);
     }
-    const url = `${base}${path16}`;
+    const url = `${base}${path20}`;
     const headers = {
       "Content-Type": "application/json",
       "User-Agent": `${CLI_USER_AGENT_NAME}/${version}`
@@ -377,10 +377,12 @@ import { Command } from "commander";
 import readline from "readline/promises";
 import { createRequire } from "module";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import path8 from "path";
+import os3 from "os";
+import path9 from "path";
 import fs from "fs";
 
 // src/commands/link.ts
+import os2 from "os";
 import path5 from "path";
 import { statSync as statSync2 } from "fs";
 
@@ -517,12 +519,12 @@ function normalizeRemote(raw) {
   const firstSlash = s.indexOf("/");
   if (firstSlash <= 0) return null;
   let host = s.slice(0, firstSlash).toLowerCase();
-  let path16 = s.slice(firstSlash + 1);
+  let path20 = s.slice(firstSlash + 1);
   if (hadScheme) host = host.replace(/:\d+$/, "");
-  path16 = path16.replace(/\/+/g, "/").replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "");
-  if (path16.length === 0) return null;
-  if (HOSTED_LOWERCASE_PATH.has(host)) path16 = path16.toLowerCase();
-  return `${host}/${path16}`;
+  path20 = path20.replace(/\/+/g, "/").replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "");
+  if (path20.length === 0) return null;
+  if (HOSTED_LOWERCASE_PATH.has(host)) path20 = path20.toLowerCase();
+  return `${host}/${path20}`;
 }
 
 // ../roadmap-schema/src/index.ts
@@ -771,6 +773,9 @@ function findRepoRoot(startDir, hasGit = dirHasGit) {
   }
   return { root: startDir, foundGit: false };
 }
+function isHomeDirectory(dir, home = os2.homedir()) {
+  return path5.resolve(dir) === path5.resolve(home);
+}
 async function handleShow(deps, projectBindingPath, mode2) {
   const startDir = resolveStartDir(process.env, process.cwd());
   const root = findRepoRoot(startDir).root;
@@ -831,10 +836,10 @@ async function handleRebind(deps, projectId, root, mode2) {
   }
 }
 async function handleUnlink(projectBindingPath, mode2) {
-  const { readFile: readFile8, writeFile: writeFile7, chmod: chmod2 } = await import("fs/promises");
+  const { readFile: readFile12, writeFile: writeFile10, chmod: chmod2 } = await import("fs/promises");
   let existing = {};
   try {
-    const raw = await readFile8(projectBindingPath, "utf8");
+    const raw = await readFile12(projectBindingPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new CliError(
@@ -849,7 +854,7 @@ async function handleUnlink(projectBindingPath, mode2) {
   }
   const { projectId: _removed, ...rest } = existing;
   void _removed;
-  await writeFile7(projectBindingPath, JSON.stringify(rest, null, 2) + "\n", { mode: 420 });
+  await writeFile10(projectBindingPath, JSON.stringify(rest, null, 2) + "\n", { mode: 420 });
   await chmod2(projectBindingPath, 420);
   if (mode2 === "json") {
     printResult({ unlinked: true, projectBindingPath }, mode2);
@@ -906,12 +911,17 @@ Proceeding anyway \u2014 verify the ID is correct.
   await writeRepoBinding(root, projectId);
   const writtenPath = path5.join(root, "nolto.json");
   let registryAdded = false;
-  try {
-    registryAdded = (await addRepoToRegistry(getRegistryPath(process.env), root)).added;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`Warning: could not update watch registry: ${message}
+  if (isHomeDirectory(root)) {
+    process.stderr.write(`Warning: refusing to add home directory ${root} to the watch registry.
+`);
+  } else {
+    try {
+      registryAdded = (await addRepoToRegistry(getRegistryPath(process.env), root)).added;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Warning: could not update watch registry: ${message}
 `);
+    }
   }
   if (mode2 === "json") {
     printResult({
@@ -1004,6 +1014,30 @@ function resolveSkillSourceDir() {
   throw new Error("Bundled roadmap-progress skill not found. Reinstall @nolto/cli.");
 }
 var VERSION_MARKER = ".nolto-skill-version";
+async function checkSkillVersionDrift(repoRoot, cliVersion) {
+  const skillDirs = [
+    path6.join(repoRoot, ".claude", "skills", "roadmap-progress"),
+    path6.join(repoRoot, ".agents", "skills", "roadmap-progress")
+  ];
+  const drifted = [];
+  for (const dir of skillDirs) {
+    if (!existsSync(dir)) continue;
+    let installed;
+    try {
+      const marker = (await readFile4(path6.join(dir, VERSION_MARKER), "utf8")).trim();
+      installed = marker.length > 0 ? marker : null;
+    } catch {
+      installed = null;
+    }
+    if (installed !== cliVersion) drifted.push({ dir, installed });
+  }
+  return drifted;
+}
+function formatSkillVersionDriftWarning(repoRoot, cliVersion, drifted) {
+  const dirs = drifted.map(({ dir }) => path6.relative(repoRoot, dir).split(path6.sep).join("/")).join(", ");
+  const installed = [...new Set(drifted.map((entry) => entry.installed ?? "unknown"))].join(", ");
+  return `roadmap-progress skill is outdated in ${dirs} (installed ${installed}, CLI ${cliVersion}). Run \`nolto init\` in this repo to update it.`;
+}
 async function installSkill(args) {
   const targetDir = path6.join(args.skillsParentDir, "roadmap-progress");
   const markerPath = path6.join(targetDir, VERSION_MARKER);
@@ -1069,14 +1103,55 @@ async function scaffoldRoadmap(args) {
   return { created: true, path: filePath };
 }
 
+// src/git-merge-driver.ts
+import { execFile as execFile2 } from "child_process";
+import { readFile as readFile5, writeFile as writeFile6 } from "fs/promises";
+import path8 from "path";
+import { promisify } from "util";
+var ATTRIBUTE_LINE = ".nolto/roadmaps/*.json merge=nolto-roadmap";
+var DRIVER_COMMAND = "nolto merge-file %A %B --base %O";
+async function ensureGitAttributes(root) {
+  const filePath = path8.join(root, ".gitattributes");
+  let content = "";
+  try {
+    content = await readFile5(filePath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  if (content.split(/\r?\n/).includes(ATTRIBUTE_LINE)) return "exists";
+  const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+  await writeFile6(filePath, content + separator + ATTRIBUTE_LINE + "\n", "utf8");
+  return "added";
+}
+async function configureMergeDriver(root, exec = async (file, args, options) => {
+  const execFileAsync = promisify(execFile2);
+  await execFileAsync(file, args, options);
+}) {
+  try {
+    await exec(
+      "git",
+      ["config", "--local", "merge.nolto-roadmap.name", "Nolto roadmap merge"],
+      { cwd: root }
+    );
+    await exec(
+      "git",
+      ["config", "--local", "merge.nolto-roadmap.driver", DRIVER_COMMAND],
+      { cwd: root }
+    );
+    return "configured";
+  } catch {
+    return "skipped";
+  }
+}
+
 // src/commands/init.ts
-var __dirname2 = path8.dirname(fileURLToPath2(import.meta.url));
+var __dirname2 = path9.dirname(fileURLToPath2(import.meta.url));
 var _require = createRequire(import.meta.url);
 function getCliVersion() {
   const candidates = [
-    path8.resolve(__dirname2, "../package.json"),
+    path9.resolve(__dirname2, "../package.json"),
     // bundled: dist/../package.json
-    path8.resolve(__dirname2, "../../package.json")
+    path9.resolve(__dirname2, "../../package.json")
     // source:  src/commands/../../package.json
   ];
   for (const pkgPath of candidates) {
@@ -1090,161 +1165,219 @@ function getCliVersion() {
   }
   return "0.0.0";
 }
+async function pickProject(rl, http, projects, promptText) {
+  if (projects.length > 0) {
+    process.stdout.write("\nProjects:\n");
+    projects.forEach((project, index) => {
+      process.stdout.write(`  (${index + 1}) ${project.name} \u2014 ${project.id}
+`);
+    });
+  } else {
+    process.stdout.write("\nNo projects yet.\n");
+  }
+  const pick = await rl.question(promptText);
+  const trimmedPick = pick.trim().toLowerCase();
+  if (trimmedPick === "c") {
+    const name = await rl.question("New project name: ");
+    if (name.trim().length === 0) {
+      throw new CliError("Project name is required.", 2);
+    }
+    const created = await http.post(
+      "/api/projects",
+      { name: name.trim() }
+    );
+    if (created.project?.id == null) {
+      throw new CliError("Project API did not return a project id.", 2);
+    }
+    const project = {
+      id: created.project.id,
+      name: created.project.name ?? name.trim()
+    };
+    process.stdout.write(`Created project ${project.name} (${project.id})
+`);
+    return project;
+  }
+  const num = parseInt(trimmedPick, 10);
+  if (!isNaN(num) && num >= 1 && num <= projects.length) {
+    return projects[num - 1];
+  }
+  return void 0;
+}
 function register2(program, deps) {
   program.command("init").description("Interactive setup: configure token, base URL, and default project.").option("--force", "Overwrite existing config without prompting").action(async (opts) => {
     const configPath = deps.configPath;
-    if (!opts.force) {
-      let existing = null;
-      try {
-        existing = await loadConfigFile(configPath);
-      } catch {
-      }
-      if (existing != null) {
-        const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
-        try {
-          const answer = await rl2.question(`Config already exists at ${configPath}. Overwrite? [y/N] `);
-          if (answer.trim().toLowerCase() !== "y") {
-            process.stdout.write("Cancelled.\n");
-            return;
-          }
-        } finally {
-          rl2.close();
-        }
-      }
-    }
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    let token = "";
     try {
-      const rawUrl = await rl.question(`Base URL [${DEFAULT_BASE_URL}]: `);
-      const baseUrl = rawUrl.trim() || DEFAULT_BASE_URL;
-      const currentToken = deps.settings.token;
-      const tokenPrompt = currentToken != null ? "API token [press Enter to keep current token]: " : "API token: ";
-      const enteredToken = await promptHidden(rl, tokenPrompt);
-      token = enteredToken.length > 0 ? enteredToken : currentToken ?? "";
-      if (token.length === 0) {
-        throw new CliError("Token is required.", 2);
-      }
-      const http = createHttpClient({
-        baseUrl,
-        token,
-        version: getCliVersion()
-      });
-      let projects = [];
-      try {
-        const result = await http.get("/api/projects");
-        projects = Array.isArray(result.projects) ? result.projects : [];
-      } catch (err) {
-        if (err instanceof CliError && err.exitCode === 3) {
-          throw new CliError(`Token rejected by ${baseUrl}`, 3, "Check that your token is valid and has not been revoked.");
+      let configureGlobal = opts.force === true;
+      if (!configureGlobal) {
+        let existing = null;
+        try {
+          existing = await loadConfigFile(configPath);
+        } catch {
+        }
+        if (existing == null || deps.settings.token == null) {
+          configureGlobal = true;
+        } else {
+          const answer = await rl.question(
+            `Config already exists at ${configPath}. Reconfigure token and base URL? [y/N] `
+          );
+          configureGlobal = answer.trim().toLowerCase() === "y";
         }
-        throw err;
       }
-      let defaultProjectId;
+      let token = deps.settings.token ?? "";
+      let baseUrl = deps.settings.baseUrl;
+      let defaultProjectId = deps.settings.defaultProjectId;
       let defaultProjectName;
-      if (projects.length > 0) {
-        process.stdout.write("\nProjects:\n");
-        projects.forEach((p, i) => {
-          process.stdout.write(`  (${i + 1}) ${p.name} \u2014 ${p.id}
-`);
+      let http;
+      let projects;
+      if (configureGlobal) {
+        const rawUrl = await rl.question(`Base URL [${DEFAULT_BASE_URL}]: `);
+        baseUrl = rawUrl.trim() || DEFAULT_BASE_URL;
+        const currentToken = deps.settings.token;
+        const tokenPrompt = currentToken != null ? "API token [press Enter to keep current token]: " : "API token: ";
+        const enteredToken = await promptHidden(rl, tokenPrompt);
+        token = enteredToken.length > 0 ? enteredToken : currentToken ?? "";
+        if (token.length === 0) {
+          throw new CliError("Token is required.", 2);
+        }
+        http = createHttpClient({
+          baseUrl,
+          token,
+          version: getCliVersion()
         });
-      } else {
-        process.stdout.write("\nNo projects yet.\n");
-      }
-      const pick = await rl.question("Default project number, 'c' to create new (or Enter to skip): ");
-      const trimmedPick = pick.trim().toLowerCase();
-      if (trimmedPick === "c") {
-        const name = await rl.question("New project name: ");
-        if (name.trim().length === 0) {
-          throw new CliError("Project name is required.", 2);
+        try {
+          const result = await http.get("/api/projects");
+          projects = Array.isArray(result.projects) ? result.projects : [];
+        } catch (err) {
+          if (err instanceof CliError && err.exitCode === 3) {
+            throw new CliError(`Token rejected by ${baseUrl}`, 3, "Check that your token is valid and has not been revoked.");
+          }
+          throw err;
         }
-        const created = await http.post(
-          "/api/projects",
-          { name: name.trim() }
+        const selected = await pickProject(
+          rl,
+          http,
+          projects,
+          "Default project number, 'c' to create new (or Enter to skip): "
         );
-        if (created.project?.id == null) {
-          throw new CliError("Project API did not return a project id.", 2);
-        }
-        defaultProjectId = created.project.id;
-        defaultProjectName = created.project.name ?? name.trim();
-        process.stdout.write(`Created project ${defaultProjectName} (${defaultProjectId})
-`);
-      } else {
-        const num = parseInt(trimmedPick, 10);
-        if (!isNaN(num) && num >= 1 && num <= projects.length) {
-          defaultProjectId = projects[num - 1].id;
-          defaultProjectName = projects[num - 1].name;
-        }
-      }
-      await saveConfigFile(configPath, {
-        token,
-        baseUrl: baseUrl !== DEFAULT_BASE_URL ? baseUrl : void 0,
-        defaultProjectId
-      });
-      const projectDisplay = defaultProjectId != null ? `${defaultProjectName ?? ""} (${defaultProjectId})` : "not set";
-      process.stdout.write(`
+        defaultProjectId = selected?.id;
+        defaultProjectName = selected?.name;
+        await saveConfigFile(configPath, {
+          token,
+          baseUrl: baseUrl !== DEFAULT_BASE_URL ? baseUrl : void 0,
+          defaultProjectId
+        });
+        const projectDisplay = defaultProjectId != null ? `${defaultProjectName ?? ""} (${defaultProjectId})` : "not set";
+        process.stdout.write(`
 Saved ${configPath}
 `);
-      process.stdout.write(`baseUrl:          ${baseUrl}
+        process.stdout.write(`baseUrl:          ${baseUrl}
 `);
-      process.stdout.write(`token:            ${maskToken(token)}  (verified)
+        process.stdout.write(`token:            ${maskToken(token)}  (verified)
 `);
-      process.stdout.write(`defaultProject:   ${projectDisplay}
+        process.stdout.write(`defaultProject:   ${projectDisplay}
 `);
-      if (defaultProjectId != null) {
-        const startDir = resolveStartDir(process.env, process.cwd());
-        const { root, foundGit } = findRepoRoot(startDir);
-        if (foundGit) {
-          const setup = await rl.question(`
+      } else {
+        const projectDisplay = defaultProjectId ?? "not set";
+        process.stdout.write(
+          `Using existing config: baseUrl=${baseUrl}, token=${maskToken(token)}, defaultProject=${projectDisplay}
+`
+        );
+      }
+      const startDir = resolveStartDir(process.env, process.cwd());
+      const { root, foundGit } = findRepoRoot(startDir);
+      if (!foundGit) {
+        process.stdout.write("\nNo git repository found here \u2014 skipped repo setup. Run `nolto init` inside a repo to set up roadmap sync.\n");
+        return;
+      }
+      if (isHomeDirectory(root)) {
+        process.stderr.write(
+          `Refusing to set up your home directory as a repository root (found ${path9.join(os3.homedir(), ".git")}). Run nolto init inside a project repository.
+`
+        );
+        return;
+      }
+      const existingBinding = deps.repoBinding?.error == null ? deps.repoBinding?.binding ?? null : null;
+      let repoProject = existingBinding != null ? { id: existingBinding.projectId, name: path9.basename(root) } : defaultProjectId != null ? { id: defaultProjectId, name: defaultProjectName ?? path9.basename(root) } : void 0;
+      if (repoProject == null) {
+        http ??= createHttpClient({ baseUrl, token, version: getCliVersion() });
+        if (projects == null) {
+          const result = await http.get("/api/projects");
+          projects = Array.isArray(result.projects) ? result.projects : [];
+        }
+        repoProject = await pickProject(
+          rl,
+          http,
+          projects,
+          "Project number for this repository, 'c' to create new (or Enter to skip): "
+        );
+      }
+      if (repoProject == null) {
+        process.stdout.write("Skipped repo setup (no project selected).\n");
+        return;
+      }
+      const setup = await rl.question(`
 Set up this repository (${root}) for roadmap sync? [Y/n] `);
-          if (setup.trim().toLowerCase() !== "n") {
-            if (deps.repoBinding?.error != null) {
-              process.stderr.write(
-                `Warning: existing nolto.json is invalid (${deps.repoBinding.error.message}). Overwriting it to repair.
+      if (setup.trim().toLowerCase() === "n") {
+        process.stdout.write("Skipped repo setup.\n");
+        return;
+      }
+      const bindingPath = deps.repoBinding?.path ?? path9.join(root, "nolto.json");
+      if (existingBinding != null) {
+        process.stdout.write(`binding:        kept ${bindingPath} (${existingBinding.projectId})
+`);
+      } else {
+        if (deps.repoBinding?.error != null) {
+          process.stderr.write(
+            `Warning: existing nolto.json is invalid (${deps.repoBinding.error.message}). Overwriting it to repair.
 `
-              );
-            }
-            await writeRepoBinding(root, defaultProjectId);
-            process.stdout.write(`binding:        wrote ${path8.join(root, "nolto.json")}
+          );
+        }
+        await writeRepoBinding(root, repoProject.id);
+        process.stdout.write(`binding:        wrote ${path9.join(root, "nolto.json")}
 `);
-            const sourceDir = resolveSkillSourceDir();
-            const version = getCliVersion();
-            const claudeInstall = await installSkill({
-              skillsParentDir: path8.join(root, ".claude", "skills"),
-              sourceDir,
-              version
-            });
-            process.stdout.write(`skill (claude): ${claudeInstall.action} ${claudeInstall.targetDir}
+      }
+      const sourceDir = resolveSkillSourceDir();
+      const version = getCliVersion();
+      const claudeInstall = await installSkill({
+        skillsParentDir: path9.join(root, ".claude", "skills"),
+        sourceDir,
+        version
+      });
+      process.stdout.write(`skill (claude): ${claudeInstall.action} ${claudeInstall.targetDir}
 `);
-            const usesAgentsTooling = fs.existsSync(path8.join(root, ".agents")) || fs.existsSync(path8.join(root, ".codex")) || fs.existsSync(path8.join(root, "AGENTS.md"));
-            if (usesAgentsTooling) {
-              const agentsInstall = await installSkill({
-                skillsParentDir: path8.join(root, ".agents", "skills"),
-                sourceDir,
-                version
-              });
-              process.stdout.write(`skill (agents): ${agentsInstall.action} ${agentsInstall.targetDir}
+      const usesAgentsTooling = fs.existsSync(path9.join(root, ".agents")) || fs.existsSync(path9.join(root, ".codex")) || fs.existsSync(path9.join(root, "AGENTS.md"));
+      if (usesAgentsTooling) {
+        const agentsInstall = await installSkill({
+          skillsParentDir: path9.join(root, ".agents", "skills"),
+          sourceDir,
+          version
+        });
+        process.stdout.write(`skill (agents): ${agentsInstall.action} ${agentsInstall.targetDir}
 `);
-            }
-            const scaffold = await scaffoldRoadmap({
-              repoRoot: root,
-              projectName: defaultProjectName ?? path8.basename(root)
-            });
-            process.stdout.write(
-              scaffold.created ? `roadmap:        created ${scaffold.path}
+      }
+      const scaffold = await scaffoldRoadmap({
+        repoRoot: root,
+        projectName: repoProject.name
+      });
+      process.stdout.write(
+        scaffold.created ? `roadmap:        created ${scaffold.path}
 ` : `roadmap:        exists ${scaffold.path}
 `
-            );
-            const registryResult = await addRepoToRegistry(getRegistryPath(process.env), root);
-            process.stdout.write(
-              registryResult.added ? `watch registry: added ${root}
+      );
+      const registryResult = await addRepoToRegistry(getRegistryPath(process.env), root);
+      process.stdout.write(
+        registryResult.added ? `watch registry: added ${root}
 ` : `watch registry: already registered
 `
-            );
-          }
-        } else {
-          process.stdout.write("\nNo git repository found here \u2014 skipped repo setup. Run `nolto init` inside a repo to set up roadmap sync.\n");
-        }
-      }
+      );
+      const attributesResult = await ensureGitAttributes(root);
+      process.stdout.write(`gitattributes:  ${attributesResult} .gitattributes
+`);
+      const mergeDriverResult = await configureMergeDriver(root, deps.gitMergeExec);
+      process.stdout.write(
+        mergeDriverResult === "configured" ? "merge driver:   configured\n" : "merge driver:   skipped (git unavailable)\n"
+      );
     } finally {
       rl.close();
     }
@@ -1464,15 +1597,15 @@ function register4(program, deps) {
 }
 
 // src/commands/sync.ts
-import { copyFile, mkdir as mkdir6, readFile as readFile5, readdir as readdir2, rename as rename2, rmdir, unlink as unlink2 } from "fs/promises";
+import { copyFile, mkdir as mkdir6, readFile as readFile6, readdir as readdir2, rename as rename2, rmdir, unlink as unlink2 } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
 
 // src/sync-repo.ts
-import path10 from "path";
+import path11 from "path";
 
 // src/sync-core.ts
 import { createHash } from "crypto";
-import path9 from "path";
+import path10 from "path";
 function sha256Hex(content) {
   return "sha256:" + createHash("sha256").update(content, "utf8").digest("hex");
 }
@@ -1493,10 +1626,10 @@ function collectPlanRefs(roadmap) {
   }
   return refs;
 }
-async function loadValidRoadmap(filePath, readFile8) {
+async function loadValidRoadmap(filePath, readFile12) {
   let raw;
   try {
-    raw = await readFile8(filePath);
+    raw = await readFile12(filePath);
   } catch {
     throw new CliError(`No roadmap found at ${filePath}. Run \`nolto init\` first.`, 2);
   }
@@ -1519,7 +1652,7 @@ async function loadValidRoadmap(filePath, readFile8) {
 async function buildSyncBody(args) {
   const planDocuments = [];
   for (const ref of collectPlanRefs(args.roadmap)) {
-    const absolute = path9.join(args.repoRoot, ref.path);
+    const absolute = path10.join(args.repoRoot, ref.path);
     if (!args.deps.fileExists(absolute)) {
       args.deps.warn(`plan file not found, skipping: ${ref.path}`);
       continue;
@@ -1566,7 +1699,7 @@ async function listRoadmapFiles(roadmapsDir, io) {
   }
 }
 async function migrateLegacyRoadmap(args) {
-  const targetPath = path10.join(args.roadmapsDir, `${args.slug}.json`);
+  const targetPath = path11.join(args.roadmapsDir, `${args.slug}.json`);
   await args.io.mkdir(args.roadmapsDir);
   try {
     await args.io.rename(args.legacyPath, targetPath);
@@ -1575,7 +1708,7 @@ async function migrateLegacyRoadmap(args) {
     await args.io.unlink(args.legacyPath);
   }
   try {
-    await args.io.rmdir(path10.dirname(args.legacyPath));
+    await args.io.rmdir(path11.dirname(args.legacyPath));
   } catch {
   }
   args.io.log(
@@ -1584,14 +1717,14 @@ async function migrateLegacyRoadmap(args) {
   return `${args.slug}.json`;
 }
 async function syncRepo(args, io) {
-  const bindingPath = path10.join(args.root, "nolto.json");
+  const bindingPath = path11.join(args.root, "nolto.json");
   const binding = await loadRepoBinding(bindingPath);
   const projectId = binding?.projectId ?? args.defaultProjectId;
   if (projectId == null) {
     throw new CliError("No project binding. Run `nolto init` or `nolto link <projectId>`.", 2);
   }
-  const roadmapsDir = path10.join(args.root, ".nolto", "roadmaps");
-  const legacyPath = path10.join(args.root, ".roadmap", "roadmap.json");
+  const roadmapsDir = path11.join(args.root, ".nolto", "roadmaps");
+  const legacyPath = path11.join(args.root, ".roadmap", "roadmap.json");
   let roadmapFiles = await listRoadmapFiles(roadmapsDir, io);
   if (roadmapFiles.length > 0) {
     if (io.fileExists(legacyPath)) {
@@ -1600,7 +1733,13 @@ async function syncRepo(args, io) {
       );
     }
   } else if (io.fileExists(legacyPath)) {
-    const migrationSlug = binding?.roadmapSlug ?? slugifyProjectId(path10.basename(args.root));
+    if (args.migrateLegacy !== true) {
+      io.warn(
+        "legacy .roadmap/roadmap.json found \u2014 run `nolto sync` once to migrate it to .nolto/roadmaps/ (watch does not migrate automatically)"
+      );
+      return { results: [], planAbsPaths: [] };
+    }
+    const migrationSlug = binding?.roadmapSlug ?? slugifyProjectId(path11.basename(args.root));
     roadmapFiles = [
       await migrateLegacyRoadmap({
         slug: migrationSlug,
@@ -1624,14 +1763,14 @@ async function syncRepo(args, io) {
           2
         );
       }
-      const filePath = path10.join(roadmapsDir, fileName);
+      const filePath = path11.join(roadmapsDir, fileName);
       return { slug, roadmap: await loadValidRoadmap(filePath, io.readFile) };
     })
   );
   const planAbsPaths = /* @__PURE__ */ new Set();
   for (const { roadmap } of roadmaps) {
     for (const ref of collectPlanRefs(roadmap)) {
-      planAbsPaths.add(path10.join(args.root, ref.path));
+      planAbsPaths.add(path11.join(args.root, ref.path));
     }
   }
   const results = [];
@@ -1659,10 +1798,13 @@ function register5(program, deps) {
       throw new CliError("No git repository found. Run inside a repo set up with `nolto init`.", 2);
     }
     const http = deps.http;
+    const warn = (line) => {
+      process.stderr.write("Warning: " + line + "\n");
+    };
     const response = await syncRepo(
-      { root, defaultProjectId: deps.settings.defaultProjectId },
+      { root, defaultProjectId: deps.settings.defaultProjectId, migrateLegacy: true },
       {
-        readFile: (p) => readFile5(p, "utf8"),
+        readFile: (p) => readFile6(p, "utf8"),
         fileExists: (p) => existsSync3(p),
         listDir: (p) => readdir2(p),
         rename: rename2,
@@ -1673,16 +1815,28 @@ function register5(program, deps) {
         repoIdentity: makeRepoIdentityResolver(deps),
         http,
         log: (line) => process.stdout.write(line + "\n"),
-        warn: (line) => process.stderr.write("Warning: " + line + "\n")
+        warn
       }
     );
-    let registryAdded = false;
     try {
-      registryAdded = (await addRepoToRegistry(getRegistryPath(process.env), root)).added;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`Warning: could not update watch registry: ${message}
+      const drifted = await checkSkillVersionDrift(root, deps.version);
+      if (drifted.length > 0) {
+        warn(formatSkillVersionDriftWarning(root, deps.version, drifted));
+      }
+    } catch {
+    }
+    let registryAdded = false;
+    if (isHomeDirectory(root)) {
+      process.stderr.write(`Warning: refusing to add home directory ${root} to the watch registry.
 `);
+    } else {
+      try {
+        registryAdded = (await addRepoToRegistry(getRegistryPath(process.env), root)).added;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Warning: could not update watch registry: ${message}
+`);
+      }
     }
     if (deps.output.mode === "json") {
       const { planAbsPaths: _planAbsPaths, ...publicResponse } = response;
@@ -1694,10 +1848,531 @@ function register5(program, deps) {
   });
 }
 
+// src/commands/diff.ts
+import { readFile as readFile7 } from "fs/promises";
+import path13 from "path";
+
+// src/roadmap-diff.ts
+function diffRoadmaps(local, server) {
+  if (local === null && server === null) return [];
+  if (local === null) return [{ kind: "meta", field: "roadmap", side: "server" }];
+  if (server === null) return [{ kind: "meta", field: "roadmap", side: "local" }];
+  const entries = [];
+  const serverPhases = new Map(server.phases.map((phase) => [phase.id, phase]));
+  for (const localPhase of local.phases) {
+    const serverPhase = serverPhases.get(localPhase.id);
+    if (!serverPhase) {
+      entries.push({
+        kind: "phase-removed",
+        id: localPhase.id,
+        title: localPhase.title,
+        side: "local"
+      });
+      continue;
+    }
+    const serverTasks = new Map(serverPhase.tasks.map((task) => [task.id, task]));
+    for (const localTask of localPhase.tasks) {
+      const serverTask = serverTasks.get(localTask.id);
+      if (!serverTask) {
+        entries.push({
+          kind: "task-removed",
+          id: localTask.id,
+          title: localTask.title,
+          side: "local"
+        });
+      } else if (localTask.status !== serverTask.status) {
+        entries.push({
+          kind: "task-status",
+          id: localTask.id,
+          title: localTask.title,
+          local: localTask.status,
+          server: serverTask.status
+        });
+      }
+    }
+    const localTaskIds = new Set(localPhase.tasks.map((task) => task.id));
+    for (const serverTask of serverPhase.tasks) {
+      if (!localTaskIds.has(serverTask.id)) {
+        entries.push({
+          kind: "task-added",
+          id: serverTask.id,
+          title: serverTask.title,
+          side: "server"
+        });
+      }
+    }
+  }
+  const localPhaseIds = new Set(local.phases.map((phase) => phase.id));
+  for (const serverPhase of server.phases) {
+    if (!localPhaseIds.has(serverPhase.id)) {
+      entries.push({
+        kind: "phase-added",
+        id: serverPhase.id,
+        title: serverPhase.title,
+        side: "server"
+      });
+    }
+  }
+  const meta = [
+    { field: "updatedAt", local: local.updatedAt, server: server.updatedAt },
+    {
+      field: "currentTaskId",
+      local: local.currentTaskId ?? null,
+      server: server.currentTaskId ?? null
+    },
+    { field: "summary", local: local.summary, server: server.summary }
+  ];
+  for (const item of meta) {
+    if (item.local !== item.server) entries.push({ kind: "meta", ...item });
+  }
+  return entries;
+}
+function truncate(value) {
+  if (value == null) return "none";
+  const singleLine = value.replace(/\s+/g, " ");
+  return singleLine.length <= 60 ? singleLine : singleLine.slice(0, 57) + "...";
+}
+function formatRoadmapDiff(slug, entries) {
+  if (entries.length === 0) return [];
+  const lines = [`${slug}:`];
+  for (const entry of entries) {
+    if (entry.kind === "task-status") {
+      lines.push(`  ${entry.id}: ${entry.local} (local) != ${entry.server} (server)`);
+    } else if (entry.kind === "task-added" || entry.kind === "task-removed") {
+      lines.push(`  ${entry.side} only task ${entry.id} "${truncate(entry.title)}"`);
+    } else if (entry.kind === "phase-added" || entry.kind === "phase-removed") {
+      lines.push(`  ${entry.side} only phase ${entry.id} "${truncate(entry.title)}"`);
+    } else if (entry.field === "roadmap") {
+      lines.push(`  ${entry.side} only roadmap`);
+    } else {
+      lines.push(
+        `  ${entry.field}: ${truncate(entry.local)} (local) != ${truncate(entry.server)} (server)`
+      );
+    }
+  }
+  return lines;
+}
+
+// src/roadmap-read.ts
+import { readdir as readdir3 } from "fs/promises";
+import path12 from "path";
+async function resolveRoadmapReadContext(deps) {
+  if (deps.settings.token == null) {
+    throw new CliError("Not authenticated. Run `nolto login` or set NOLTO_TOKEN.", 3);
+  }
+  const startDir = resolveStartDir(process.env, process.cwd());
+  const { root, foundGit } = findRepoRoot(startDir);
+  if (!foundGit) {
+    throw new CliError("No git repository found. Run inside a repo set up with `nolto init`.", 2);
+  }
+  const binding = await loadRepoBinding(path12.join(root, "nolto.json"));
+  const projectId = binding?.projectId ?? deps.settings.defaultProjectId;
+  if (projectId == null) {
+    throw new CliError("No project binding. Run `nolto init` or `nolto link <projectId>`.", 2);
+  }
+  return { root, projectId };
+}
+async function listLocalRoadmapSlugs(root) {
+  try {
+    const entries = await readdir3(path12.join(root, ".nolto", "roadmaps"));
+    return entries.filter((entry) => entry.endsWith(".json")).map((entry) => entry.slice(0, -".json".length)).sort();
+  } catch (err) {
+    if (err != null && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+// src/commands/diff.ts
+function register6(program, deps) {
+  program.command("diff [slug]").description("Compare local roadmaps with the server without changing either side.").action(async (requestedSlug) => {
+    const { root, projectId } = await resolveRoadmapReadContext(deps);
+    const list = await deps.http.get(
+      `/api/projects/${projectId}/roadmaps`
+    );
+    const serverBySlug = new Map(list.roadmaps.map((roadmap) => [roadmap.slug, roadmap]));
+    const localSlugs = await listLocalRoadmapSlugs(root);
+    const localSlugSet = new Set(localSlugs);
+    const allSlugs = [.../* @__PURE__ */ new Set([...localSlugs, ...serverBySlug.keys()])].sort();
+    if (requestedSlug != null && !allSlugs.includes(requestedSlug)) {
+      throw new CliError(
+        `Roadmap "${requestedSlug}" was not found locally or on the server.`,
+        2
+      );
+    }
+    const targetSlugs = requestedSlug == null ? allSlugs : [requestedSlug];
+    let differing = 0;
+    for (const slug of targetSlugs) {
+      let local = null;
+      if (localSlugSet.has(slug)) {
+        const localPath = path13.join(root, ".nolto", "roadmaps", `${slug}.json`);
+        try {
+          local = await loadValidRoadmap(localPath, (filePath) => readFile7(filePath, "utf8"));
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          process.stderr.write(`Warning: could not diff ${slug}.json: ${message}
+`);
+          process.stdout.write(`${slug}:
+  local roadmap is present but invalid
+`);
+          differing += 1;
+          continue;
+        }
+      }
+      let server = null;
+      if (serverBySlug.has(slug) && local !== null) {
+        const response = await deps.http.get(
+          `/api/projects/${projectId}/roadmaps/${encodeURIComponent(slug)}`
+        );
+        const validation = validateRoadmap(response.roadmap);
+        if (validation.errors.length > 0) {
+          throw new CliError(
+            `Server roadmap "${slug}" failed validation: ${validation.errors.join("; ")}`,
+            5
+          );
+        }
+        server = response.roadmap;
+      }
+      const entries = local === null && serverBySlug.has(slug) ? [{ kind: "meta", field: "roadmap", side: "server" }] : diffRoadmaps(local, server);
+      if (entries.length === 0) continue;
+      differing += 1;
+      process.stdout.write(formatRoadmapDiff(slug, entries).join("\n") + "\n");
+    }
+    if (differing === 0) {
+      process.stdout.write("Up to date with the server.\n");
+      process.exitCode = 0;
+    } else {
+      process.stdout.write(`${differing} roadmap(s) differ
+`);
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/commands/pull.ts
+import { mkdir as mkdir7, readFile as readFile8, writeFile as writeFile7 } from "fs/promises";
+import path14 from "path";
+
+// src/roadmap-merge.ts
+import { isDeepStrictEqual } from "util";
+function taskLocations(roadmap) {
+  const result = /* @__PURE__ */ new Map();
+  for (const phase of roadmap?.phases ?? []) {
+    for (const task of phase.tasks) result.set(task.id, { task, phaseId: phase.id });
+  }
+  return result;
+}
+function chooseField(args) {
+  if (args.baseExists && isDeepStrictEqual(args.ours, args.base)) return args.theirs;
+  if (args.baseExists && isDeepStrictEqual(args.theirs, args.base)) return args.ours;
+  if (isDeepStrictEqual(args.ours, args.theirs)) return args.ours;
+  return args.newer === "ours" ? args.ours : args.theirs;
+}
+function chooseStatus(base, ours, theirs) {
+  if (base !== void 0) {
+    const oursChanged = ours.status !== base.status;
+    const theirsChanged = theirs.status !== base.status;
+    if (!oursChanged) return theirs.status;
+    if (!theirsChanged) return ours.status;
+  }
+  const candidates = [ours, theirs];
+  if (candidates.some((task) => task.status === "done" && task.completedAt != null)) {
+    return "done";
+  }
+  for (const status of ["blocked", "in-progress", "todo"]) {
+    if (candidates.some((task) => task.status === status)) return status;
+  }
+  return base?.status !== "done" ? base?.status ?? "todo" : "todo";
+}
+function earliest(values) {
+  return values.filter((value) => value != null).sort((a, b) => Date.parse(a) - Date.parse(b))[0];
+}
+function latest(values) {
+  return values.filter((value) => value != null).sort((a, b) => Date.parse(b) - Date.parse(a))[0];
+}
+function assignOptional(target, key, value) {
+  if (value !== void 0) Object.assign(target, { [key]: value });
+}
+function cloneSingleTask(task) {
+  const cloned = { ...task };
+  if (task.dependsOn !== void 0) cloned.dependsOn = [...task.dependsOn];
+  if (cloned.status !== "done") delete cloned.completedAt;
+  return cloned;
+}
+function mergeTask(args) {
+  const baseExists = args.base !== void 0;
+  const status = chooseStatus(args.base, args.ours, args.theirs);
+  const merged = {
+    id: args.ours.id,
+    title: chooseField({
+      baseExists,
+      base: args.base?.title,
+      ours: args.ours.title,
+      theirs: args.theirs.title,
+      newer: args.newer
+    }),
+    status
+  };
+  assignOptional(
+    merged,
+    "startedAt",
+    earliest([args.base?.startedAt, args.ours.startedAt, args.theirs.startedAt])
+  );
+  if (status === "done") {
+    assignOptional(
+      merged,
+      "completedAt",
+      latest([args.base?.completedAt, args.ours.completedAt, args.theirs.completedAt])
+    );
+  }
+  assignOptional(merged, "note", chooseField({
+    baseExists,
+    base: args.base?.note,
+    ours: args.ours.note,
+    theirs: args.theirs.note,
+    newer: args.newer
+  }));
+  assignOptional(merged, "plan", chooseField({
+    baseExists,
+    base: args.base?.plan,
+    ours: args.ours.plan,
+    theirs: args.theirs.plan,
+    newer: args.newer
+  }));
+  const dependsOn = [
+    ...args.ours.dependsOn ?? [],
+    ...args.theirs.dependsOn ?? []
+  ].filter((id, index, values) => values.indexOf(id) === index);
+  if (dependsOn.length > 0) merged.dependsOn = dependsOn;
+  return merged;
+}
+function shouldKeep(base, ours, theirs) {
+  if (base === void 0) return ours !== void 0 || theirs !== void 0;
+  if (ours === void 0 && theirs === void 0) return false;
+  if (ours === void 0) return !isDeepStrictEqual(theirs, base);
+  if (theirs === void 0) return !isDeepStrictEqual(ours, base);
+  return true;
+}
+function orderTasks(args) {
+  const oursPhase = args.ours.phases.find((phase) => phase.id === args.phaseId);
+  const theirsPhase = args.theirs.phases.find((phase) => phase.id === args.phaseId);
+  const ordered = (oursPhase?.tasks ?? []).map((task) => task.id).filter((id) => args.taskIds.has(id));
+  let nearestCommon = null;
+  let insertAfter = null;
+  for (const task of theirsPhase?.tasks ?? []) {
+    if (!args.taskIds.has(task.id)) continue;
+    if (args.oursLocations.has(task.id)) {
+      if (ordered.includes(task.id)) {
+        nearestCommon = task.id;
+        insertAfter = task.id;
+      }
+      continue;
+    }
+    if (nearestCommon === null || insertAfter === null) {
+      ordered.push(task.id);
+      continue;
+    }
+    const index = ordered.indexOf(insertAfter);
+    ordered.splice(index + 1, 0, task.id);
+    insertAfter = task.id;
+  }
+  return ordered;
+}
+function mergeRoadmaps(args) {
+  const newer = Date.parse(args.theirs.updatedAt) > Date.parse(args.ours.updatedAt) ? "theirs" : "ours";
+  const newerRoadmap = newer === "ours" ? args.ours : args.theirs;
+  const olderRoadmap = newer === "ours" ? args.theirs : args.ours;
+  const basePhases = new Map((args.base?.phases ?? []).map((phase) => [phase.id, phase]));
+  const oursPhases = new Map(args.ours.phases.map((phase) => [phase.id, phase]));
+  const theirsPhases = new Map(args.theirs.phases.map((phase) => [phase.id, phase]));
+  const baseLocations = taskLocations(args.base);
+  const oursLocations = taskLocations(args.ours);
+  const theirsLocations = taskLocations(args.theirs);
+  const keptTasks = /* @__PURE__ */ new Map();
+  const targetPhaseByTask = /* @__PURE__ */ new Map();
+  const taskIds = /* @__PURE__ */ new Set([
+    ...baseLocations.keys(),
+    ...oursLocations.keys(),
+    ...theirsLocations.keys()
+  ]);
+  for (const taskId of taskIds) {
+    const baseLocation = baseLocations.get(taskId);
+    const oursLocation = oursLocations.get(taskId);
+    const theirsLocation = theirsLocations.get(taskId);
+    if (!shouldKeep(baseLocation, oursLocation, theirsLocation)) continue;
+    const task = oursLocation !== void 0 && theirsLocation !== void 0 ? mergeTask({
+      base: baseLocation?.task,
+      ours: oursLocation.task,
+      theirs: theirsLocation.task,
+      newer
+    }) : cloneSingleTask((oursLocation ?? theirsLocation).task);
+    keptTasks.set(taskId, task);
+    targetPhaseByTask.set(taskId, (oursLocation ?? theirsLocation).phaseId);
+  }
+  const keptPhaseIds = /* @__PURE__ */ new Set();
+  const allPhaseIds = /* @__PURE__ */ new Set([
+    ...basePhases.keys(),
+    ...oursPhases.keys(),
+    ...theirsPhases.keys()
+  ]);
+  for (const phaseId of allPhaseIds) {
+    if (shouldKeep(basePhases.get(phaseId), oursPhases.get(phaseId), theirsPhases.get(phaseId))) {
+      keptPhaseIds.add(phaseId);
+    }
+  }
+  const phaseOrder = [
+    ...args.ours.phases.map((phase) => phase.id).filter((id) => keptPhaseIds.has(id)),
+    ...args.theirs.phases.map((phase) => phase.id).filter((id) => keptPhaseIds.has(id) && !oursPhases.has(id))
+  ];
+  const phases = phaseOrder.map((phaseId) => {
+    const base = basePhases.get(phaseId);
+    const ours = oursPhases.get(phaseId);
+    const theirs = theirsPhases.get(phaseId);
+    const source = ours ?? theirs;
+    const title = ours !== void 0 && theirs !== void 0 ? chooseField({
+      baseExists: base !== void 0,
+      base: base?.title,
+      ours: ours.title,
+      theirs: theirs.title,
+      newer
+    }) : source.title;
+    const plan = ours !== void 0 && theirs !== void 0 ? chooseField({
+      baseExists: base !== void 0,
+      base: base?.plan,
+      ours: ours.plan,
+      theirs: theirs.plan,
+      newer
+    }) : source.plan;
+    const phaseTaskIds = new Set(
+      [...keptTasks.keys()].filter((taskId) => targetPhaseByTask.get(taskId) === phaseId)
+    );
+    const tasks = orderTasks({
+      phaseId,
+      taskIds: phaseTaskIds,
+      ours: args.ours,
+      theirs: args.theirs,
+      oursLocations
+    }).map((taskId) => keptTasks.get(taskId));
+    const phase = { id: phaseId, title, status: "todo", tasks };
+    if (plan !== void 0) phase.plan = plan;
+    phase.status = derivePhaseStatus(phase);
+    return phase;
+  });
+  const mergedTasks = new Map(
+    phases.flatMap((phase) => phase.tasks.map((task) => [task.id, task]))
+  );
+  const validCurrentTask = (roadmap) => {
+    const id = roadmap.currentTaskId ?? null;
+    return id != null && mergedTasks.get(id)?.status === "in-progress" ? id : null;
+  };
+  const merged = {
+    schemaVersion: 2,
+    project: { ...newerRoadmap.project },
+    updatedAt: newerRoadmap.updatedAt,
+    currentTaskId: validCurrentTask(newerRoadmap) ?? validCurrentTask(olderRoadmap),
+    summary: newerRoadmap.summary,
+    phases
+  };
+  const validation = validateRoadmap(merged);
+  if (validation.errors.length > 0) {
+    throw new CliError(
+      `Merged roadmap failed validation:
+  ${validation.errors.join("\n  ")}`,
+      1
+    );
+  }
+  return merged;
+}
+
+// src/commands/pull.ts
+async function readExisting(filePath) {
+  try {
+    return await readFile8(filePath, "utf8");
+  } catch (err) {
+    if (err != null && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+}
+function register7(program, deps) {
+  program.command("pull [slug]").description(
+    "Pull server roadmaps, optionally merging them with valid local copies."
+  ).option("--merge", "Structurally merge server and local roadmap changes").action(async (requestedSlug, opts) => {
+    const { root, projectId } = await resolveRoadmapReadContext(deps);
+    const list = await deps.http.get(
+      `/api/projects/${projectId}/roadmaps`
+    );
+    const serverBySlug = new Map(list.roadmaps.map((roadmap) => [roadmap.slug, roadmap]));
+    if (requestedSlug != null && !serverBySlug.has(requestedSlug)) {
+      throw new CliError(`Roadmap "${requestedSlug}" was not found on the server.`, 2);
+    }
+    const targets = requestedSlug == null ? [...serverBySlug.values()] : [serverBySlug.get(requestedSlug)];
+    const roadmapsDir = path14.join(root, ".nolto", "roadmaps");
+    for (const summary of targets) {
+      const response = await deps.http.get(
+        `/api/projects/${projectId}/roadmaps/${encodeURIComponent(summary.slug)}`
+      );
+      const validation = validateRoadmap(response.roadmap);
+      if (validation.errors.length > 0) {
+        throw new CliError(
+          `Server roadmap "${summary.slug}" failed validation: ${validation.errors.join("; ")}`,
+          5
+        );
+      }
+      const filePath = path14.join(roadmapsDir, `${summary.slug}.json`);
+      const existing = await readExisting(filePath);
+      let roadmap = response.roadmap;
+      let outputVerb = "pulled";
+      if (opts.merge === true && existing !== null) {
+        let local;
+        try {
+          local = JSON.parse(existing);
+        } catch {
+          process.stderr.write(
+            `Warning: skipped ${summary.slug}.json because the local roadmap contains malformed JSON.
+`
+          );
+          continue;
+        }
+        const localValidation = validateRoadmap(local);
+        if (localValidation.errors.length > 0) {
+          process.stderr.write(
+            `Warning: skipped ${summary.slug}.json because the local roadmap is invalid: ${localValidation.errors.join("; ")}
+`
+          );
+          continue;
+        }
+        roadmap = mergeRoadmaps({
+          base: null,
+          ours: local,
+          theirs: response.roadmap
+        });
+        outputVerb = "merged";
+      }
+      const serialized = JSON.stringify(roadmap, null, 2) + "\n";
+      if (existing === serialized) {
+        process.stdout.write(`unchanged ${summary.slug}.json
+`);
+        continue;
+      }
+      await mkdir7(roadmapsDir, { recursive: true });
+      await writeFile7(filePath, serialized, "utf8");
+      process.stdout.write(
+        outputVerb === "merged" ? `merged ${summary.slug}.json
+` : `pulled ${summary.slug}.json (${summary.taskDone}/${summary.taskTotal} done)
+`
+      );
+    }
+    process.stdout.write("Review with git diff before committing.\n");
+  });
+}
+
 // src/commands/watch.ts
-import { copyFile as copyFile2, mkdir as mkdir7, readFile as readFile6, readdir as readdir3, rename as rename3, rmdir as rmdir2, unlink as unlink3 } from "fs/promises";
+import { copyFile as copyFile2, mkdir as mkdir8, readFile as readFile9, readdir as readdir4, rename as rename3, rmdir as rmdir2, unlink as unlink3 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
-import path12 from "path";
+import path16 from "path";
 import chokidar from "chokidar";
 
 // src/watch-core.ts
@@ -1803,8 +2478,8 @@ var RepoWatch = class {
 };
 
 // src/service-install.ts
-import path11 from "path";
-import os2 from "os";
+import path15 from "path";
+import os4 from "os";
 function buildUnitFile(args) {
   return [
     "[Unit]",
@@ -1823,8 +2498,8 @@ function buildUnitFile(args) {
 }
 function getUnitPath(env) {
   const xdg = env["XDG_CONFIG_HOME"];
-  const base = xdg != null && xdg.length > 0 ? xdg : path11.join(os2.homedir(), ".config");
-  return path11.join(base, "systemd", "user", "nolto-watch.service");
+  const base = xdg != null && xdg.length > 0 ? xdg : path15.join(os4.homedir(), ".config");
+  return path15.join(base, "systemd", "user", "nolto-watch.service");
 }
 async function installServiceWith(deps) {
   if (deps.platform !== "linux") {
@@ -1835,7 +2510,7 @@ async function installServiceWith(deps) {
     );
   }
   const unitPath = getUnitPath(deps.env);
-  await deps.mkdir(path11.dirname(unitPath));
+  await deps.mkdir(path15.dirname(unitPath));
   await deps.writeFile(unitPath, buildUnitFile({ nodePath: deps.nodePath, scriptPath: deps.scriptPath }));
   deps.log(`Wrote ${unitPath}`);
   const reload = await deps.exec(["systemctl", "--user", "daemon-reload"]);
@@ -1849,18 +2524,18 @@ async function installServiceWith(deps) {
   deps.log("Service nolto-watch enabled and started. Logs: journalctl --user -u nolto-watch -f");
 }
 async function installService() {
-  const { writeFile: writeFile7, mkdir: mkdir9 } = await import("fs/promises");
-  const { execFile: execFile3 } = await import("child_process");
-  const { promisify: promisify2 } = await import("util");
-  const execFileAsync = promisify2(execFile3);
+  const { writeFile: writeFile10, mkdir: mkdir10 } = await import("fs/promises");
+  const { execFile: execFile4 } = await import("child_process");
+  const { promisify: promisify3 } = await import("util");
+  const execFileAsync = promisify3(execFile4);
   await installServiceWith({
     platform: process.platform,
     env: process.env,
     nodePath: process.execPath,
-    scriptPath: path11.resolve(process.argv[1] ?? ""),
-    writeFile: (p, content) => writeFile7(p, content, "utf8"),
+    scriptPath: path15.resolve(process.argv[1] ?? ""),
+    writeFile: (p, content) => writeFile10(p, content, "utf8"),
     mkdir: async (p) => {
-      await mkdir9(p, { recursive: true });
+      await mkdir10(p, { recursive: true });
     },
     exec: async (cmd) => {
       try {
@@ -1915,9 +2590,9 @@ async function uninstallServiceWith(deps) {
 }
 async function uninstallService() {
   const { unlink: unlink4 } = await import("fs/promises");
-  const { execFile: execFile3 } = await import("child_process");
-  const { promisify: promisify2 } = await import("util");
-  const execFileAsync = promisify2(execFile3);
+  const { execFile: execFile4 } = await import("child_process");
+  const { promisify: promisify3 } = await import("util");
+  const execFileAsync = promisify3(execFile4);
   await uninstallServiceWith({
     platform: process.platform,
     env: process.env,
@@ -1937,7 +2612,7 @@ async function uninstallService() {
 }
 
 // src/commands/watch.ts
-function register6(program, deps) {
+function register8(program, deps) {
   program.command("watch").description("Watch every registered repository's roadmap + plan files and sync on change.").option("--debounce <ms>", "Debounce window in milliseconds", "2000").option("--install-service", "Install and enable a systemd user unit (nolto-watch) instead of watching").option("--uninstall-service", "Stop and remove the systemd user unit (nolto-watch) instead of watching").action(async (opts) => {
     if (opts.installService && opts.uninstallService) {
       throw new CliError("--install-service and --uninstall-service cannot be used together.", 2);
@@ -1974,27 +2649,31 @@ function register6(program, deps) {
       token: deps.settings.token
     });
     const startRepo = (root) => {
-      const roadmapsPath = path12.join(root, ".nolto", "roadmaps");
-      const legacyRoadmapPath = path12.join(root, ".roadmap", "roadmap.json");
+      const roadmapsPath = path16.join(root, ".nolto", "roadmaps");
+      const legacyRoadmapPath = path16.join(root, ".roadmap", "roadmap.json");
+      const warn = (line) => {
+        process.stderr.write(`Warning: [${path16.basename(root)}] ${line}
+`);
+      };
       const watcher = chokidar.watch([roadmapsPath, legacyRoadmapPath], { ignoreInitial: true });
       const repoWatch = new RepoWatch(root, {
         sync: () => syncRepo(
-          { root, defaultProjectId: deps.settings.defaultProjectId },
+          // #316: watch must warn about legacy roadmaps without migrating them.
+          { root, defaultProjectId: deps.settings.defaultProjectId, migrateLegacy: false },
           {
-            readFile: (p) => readFile6(p, "utf8"),
+            readFile: (p) => readFile9(p, "utf8"),
             fileExists: (p) => existsSync4(p),
-            listDir: (p) => readdir3(p),
+            listDir: (p) => readdir4(p),
             rename: rename3,
             copyFile: copyFile2,
-            mkdir: (p) => mkdir7(p, { recursive: true }).then(() => void 0),
+            mkdir: (p) => mkdir8(p, { recursive: true }).then(() => void 0),
             unlink: unlink3,
             rmdir: rmdir2,
             repoIdentity: makeRepoIdentityResolver(deps),
             http,
-            log: (line) => process.stdout.write(`[${path12.basename(root)}] ${line}
+            log: (line) => process.stdout.write(`[${path16.basename(root)}] ${line}
 `),
-            warn: (line) => process.stderr.write(`Warning: [${path12.basename(root)}] ${line}
-`)
+            warn
           }
         ),
         watcher,
@@ -2005,6 +2684,12 @@ function register6(program, deps) {
         warn: (line) => process.stderr.write(line + "\n")
       });
       watcher.on("all", (_event, filePath) => repoWatch.handleEvent(filePath));
+      void checkSkillVersionDrift(root, deps.version).then((drifted) => {
+        if (drifted.length > 0) {
+          warn(formatSkillVersionDriftWarning(root, deps.version, drifted));
+        }
+      }).catch(() => {
+      });
       void repoWatch.flush();
       return { stop: () => watcher.close() };
     };
@@ -2049,25 +2734,25 @@ function register6(program, deps) {
 }
 
 // src/update-cli.ts
-import { execFile as execFile2 } from "child_process";
+import { execFile as execFile3 } from "child_process";
 import { existsSync as existsSync5 } from "fs";
 import { realpath } from "fs/promises";
 import { createRequire as createRequire2 } from "module";
-import path14 from "path";
+import path18 from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import { promisify } from "util";
+import { promisify as promisify2 } from "util";
 
 // src/update-notifier.ts
-import { readFile as readFile7, writeFile as writeFile6, mkdir as mkdir8 } from "fs/promises";
+import { readFile as readFile10, writeFile as writeFile8, mkdir as mkdir9 } from "fs/promises";
 import https from "https";
-import path13 from "path";
+import path17 from "path";
 var PACKAGE = "@nolto/cli";
 var CACHE_FILE = "update-check.json";
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 var REQUEST_TIMEOUT_MS = 2e3;
-function isNewerVersion(latest, current) {
+function isNewerVersion(latest2, current) {
   const parts = (v) => v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
-  const a = parts(latest);
+  const a = parts(latest2);
   const b = parts(current);
   for (let i = 0; i < 3; i++) {
     const x = a[i] ?? 0;
@@ -2076,9 +2761,9 @@ function isNewerVersion(latest, current) {
   }
   return false;
 }
-function formatUpdateNotice(latest, current) {
+function formatUpdateNotice(latest2, current) {
   return `
-Update available: ${current} \u2192 ${latest}  \xB7  run \`nolto update\`
+Update available: ${current} \u2192 ${latest2}  \xB7  run \`nolto update\`
 `;
 }
 function isDisabled(env) {
@@ -2117,22 +2802,22 @@ function fetchLatestFromRegistry(timeoutMs = REQUEST_TIMEOUT_MS, opts = {}) {
     req.on("error", () => resolve(null));
   });
 }
-async function writeUpdateCache(cachePath, now, latest) {
-  await mkdir8(path13.dirname(cachePath), { recursive: true });
-  const payload = { checkedAt: now, latest };
-  await writeFile6(cachePath, JSON.stringify(payload), { mode: 384 });
+async function writeUpdateCache(cachePath, now, latest2) {
+  await mkdir9(path17.dirname(cachePath), { recursive: true });
+  const payload = { checkedAt: now, latest: latest2 };
+  await writeFile8(cachePath, JSON.stringify(payload), { mode: 384 });
 }
 async function refreshCache(cachePath, now, fetchLatest) {
-  const latest = await fetchLatest();
-  if (!latest) return;
-  await writeUpdateCache(cachePath, now, latest).catch(() => void 0);
+  const latest2 = await fetchLatest();
+  if (!latest2) return;
+  await writeUpdateCache(cachePath, now, latest2).catch(() => void 0);
 }
 async function checkForUpdate(opts) {
   if (isDisabled(opts.env)) return null;
-  const cachePath = path13.join(opts.configDir, CACHE_FILE);
+  const cachePath = path17.join(opts.configDir, CACHE_FILE);
   let cache = {};
   try {
-    cache = JSON.parse(await readFile7(cachePath, "utf8"));
+    cache = JSON.parse(await readFile10(cachePath, "utf8"));
   } catch {
   }
   if (typeof cache.checkedAt !== "number" || opts.now - cache.checkedAt > CACHE_TTL_MS) {
@@ -2148,13 +2833,13 @@ async function checkForUpdate(opts) {
 async function notifyUpdate(opts) {
   try {
     if (opts.isJson || !process.stderr.isTTY) return;
-    const latest = await checkForUpdate({
+    const latest2 = await checkForUpdate({
       current: opts.current,
       configDir: getConfigDir(opts.env),
       env: opts.env,
       now: opts.now
     });
-    if (latest) process.stderr.write(formatUpdateNotice(latest, opts.current));
+    if (latest2) process.stderr.write(formatUpdateNotice(latest2, opts.current));
   } catch {
   }
 }
@@ -2205,14 +2890,14 @@ async function updateCliWith(deps) {
   if (!isInsideGlobalPackage(deps.scriptPath, globalRoot, deps.platform)) {
     throw notGlobalError(deps.scriptPath);
   }
-  const latest = await deps.fetchLatest();
-  if (latest == null) {
+  const latest2 = await deps.fetchLatest();
+  if (latest2 == null) {
     throw new CliError(
       "Could not reach the npm registry to check for the latest @nolto/cli version.",
       5
     );
   }
-  if (!isNewerVersion(latest, deps.currentVersion)) {
+  if (!isNewerVersion(latest2, deps.currentVersion)) {
     deps.log(`Already up to date (${PACKAGE2} ${deps.currentVersion}).`);
     return {
       status: "up-to-date",
@@ -2225,7 +2910,7 @@ async function updateCliWith(deps) {
     "npm",
     "install",
     "-g",
-    `${PACKAGE2}@${latest}`
+    `${PACKAGE2}@${latest2}`
   ]);
   if (installResult.code !== 0) {
     const detail = stderrTail(installResult.stderr);
@@ -2235,11 +2920,11 @@ async function updateCliWith(deps) {
       /EACCES|permission denied/i.test(installResult.stderr) ? "Permission denied \u2014 check your npm global prefix (npm config get prefix) or re-run with elevated permissions." : void 0
     );
   }
-  deps.log(`Updated ${PACKAGE2} ${deps.currentVersion} \u2192 ${latest}.`);
+  deps.log(`Updated ${PACKAGE2} ${deps.currentVersion} \u2192 ${latest2}.`);
   await deps.writeCache(
-    path14.join(deps.configDir, UPDATE_CACHE_FILE),
+    path18.join(deps.configDir, UPDATE_CACHE_FILE),
     deps.now,
-    latest
+    latest2
   ).catch(() => void 0);
   let watchService = "not-installed";
   const unitPath = getUnitPath(deps.env);
@@ -2263,22 +2948,22 @@ async function updateCliWith(deps) {
   return {
     status: "updated",
     from: deps.currentVersion,
-    to: latest,
+    to: latest2,
     watchService
   };
 }
 function getCurrentVersion() {
-  const dirname = path14.dirname(fileURLToPath3(import.meta.url));
+  const dirname = path18.dirname(fileURLToPath3(import.meta.url));
   const require3 = createRequire2(import.meta.url);
   try {
-    const pkg = require3(path14.resolve(dirname, "../package.json"));
+    const pkg = require3(path18.resolve(dirname, "../package.json"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
   }
 }
 async function updateCli(opts = {}) {
-  const execFileAsync = promisify(execFile2);
+  const execFileAsync = promisify2(execFile3);
   const scriptPath = await realpath(process.argv[1] ?? "");
   return updateCliWith({
     currentVersion: getCurrentVersion(),
@@ -2310,7 +2995,7 @@ async function updateCli(opts = {}) {
 }
 
 // src/commands/update.ts
-function register7(program, deps) {
+function register9(program, deps) {
   program.command("update").description("Update @nolto/cli to the latest version and restart the watch service if installed").action(async () => {
     const mode2 = deps.output.mode;
     const result = await updateCli({ quiet: mode2 === "json" });
@@ -2320,6 +3005,46 @@ function register7(program, deps) {
   });
 }
 
+// src/commands/merge-file.ts
+import { readFile as readFile11, writeFile as writeFile9 } from "fs/promises";
+async function readRoadmap(filePath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile11(filePath, "utf8"));
+  } catch (err) {
+    const message = err instanceof SyntaxError ? "malformed JSON" : String(err);
+    throw new CliError(`${filePath}: ${message}`, 1);
+  }
+  const validation = validateRoadmap(parsed);
+  if (validation.errors.length > 0) {
+    throw new CliError(
+      `${filePath} failed validation:
+  ${validation.errors.join("\n  ")}`,
+      1
+    );
+  }
+  return parsed;
+}
+function register10(program) {
+  program.command("merge-file <ours> <theirs>").description(
+    'Structurally merge roadmap files for Git.\ngit config merge.nolto-roadmap.driver "nolto merge-file %A %B --base %O"'
+  ).option("--base <path>", "Common ancestor roadmap file").option("--output <path>", "Write the result here (defaults to <ours>)").action(async (oursPath, theirsPath, opts) => {
+    const ours = await readRoadmap(oursPath);
+    const theirs = await readRoadmap(theirsPath);
+    const base = opts.base == null ? null : await readRoadmap(opts.base);
+    const merged = mergeRoadmaps({ base, ours, theirs });
+    await writeFile9(
+      opts.output ?? oursPath,
+      JSON.stringify(merged, null, 2) + "\n",
+      "utf8"
+    );
+    const taskCount = merged.phases.reduce((total, phase) => total + phase.tasks.length, 0);
+    process.stderr.write(`merged roadmap (${taskCount} tasks)
+`);
+    process.exitCode = 0;
+  });
+}
+
 // src/program.ts
 function stripCommanderErrorPrefix(msg) {
   return msg.startsWith("error: ") ? msg.slice("error: ".length) : msg;
@@ -2335,9 +3060,12 @@ function buildProgram(deps) {
   register5(program, deps);
   register6(program, deps);
   register7(program, deps);
+  register8(program, deps);
+  register9(program, deps);
+  register10(program);
   program.hook("preAction", (_thisCommand, actionCommand) => {
     const bindingError = deps.repoBinding?.error;
-    const bindingExemptCommands = ["init", "link", "update"];
+    const bindingExemptCommands = ["init", "link", "update", "merge-file"];
     if (bindingError != null && !bindingExemptCommands.includes(actionCommand.name())) {
       throw bindingError;
     }
@@ -2346,11 +3074,11 @@ function buildProgram(deps) {
 }
 
 // src/index.ts
-var __dirname3 = path15.dirname(fileURLToPath4(import.meta.url));
+var __dirname3 = path19.dirname(fileURLToPath4(import.meta.url));
 var require2 = createRequire3(import.meta.url);
 function getVersion() {
   try {
-    const pkgPath = path15.resolve(__dirname3, "../package.json");
+    const pkgPath = path19.resolve(__dirname3, "../package.json");
     const pkg = require2(pkgPath);
     return pkg.version ?? "0.0.0";
   } catch {