@jazpiper/rules-doctor 0.2.0 → 0.3.1

package/dist/index.js

@@ -1,9 +1,19 @@
 #!/usr/bin/env node
-const { dirname, isAbsolute, resolve } = require("node:path");
-const { existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+const { dirname, isAbsolute, relative, resolve } = require("node:path");
+const { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
 const { ADAPTERS, ADAPTERS_BY_ID } = require("./adapters");
 
 const RULES_RELATIVE_PATH = ".agentrules/rules.yaml";
+const IMPORT_REPORT_RELATIVE_PATH = ".agentrules/import-report.md";
+const REQUIRED_RULE_KEYS = [
+  "version",
+  "mission",
+  "workflow",
+  "commands",
+  "done",
+  "approvals",
+  "targets",
+];
 
 function usage() {
   const targets = ADAPTERS.map((adapter) => adapter.id).join("|");
@@ -11,10 +21,12 @@ function usage() {
     "rules-doctor",
     "",
     "Usage:",
-    "  rules-doctor init",
-    `  rules-doctor sync [--target all|${targets}|<comma-separated-targets>]`,
-    "  rules-doctor analyze",
-    "  rules-doctor targets list",
+    "  rules-doctor init [--import]",
+    `  rules-doctor sync [--target all|${targets}|<comma-separated-targets>] [--diff] [--write] [--backup]`,
+    `  rules-doctor check [--target all|${targets}|<comma-separated-targets>] [--diff]`,
+    "",
+    "Notes:",
+    "  - sync defaults to dry-run. Add --write to apply changes.",
   ].join("\n");
 }
 
@@ -45,12 +57,12 @@ function readJsonFile(filePath) {
 
 function stripQuotes(value) {
   const trimmed = value.trim();
-  if (
-    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-    (trimmed.startsWith("'") && trimmed.endsWith("'"))
-  ) {
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1).replace(/''/g, "'");
+  }
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
     try {
-      return JSON.parse(trimmed.replace(/'/g, '"'));
+      return JSON.parse(trimmed);
     } catch {
       return trimmed.slice(1, -1);
     }
@@ -58,8 +70,285 @@ function stripQuotes(value) {
   return trimmed;
 }
 
+function stripInlineComment(value) {
+  const input = String(value);
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (char === "\\" && inDouble) {
+      escaped = true;
+      continue;
+    }
+
+    if (char === "'" && !inDouble) {
+      if (inSingle && input[index + 1] === "'") {
+        index += 1;
+        continue;
+      }
+      inSingle = !inSingle;
+      continue;
+    }
+
+    if (char === '"' && !inSingle) {
+      inDouble = !inDouble;
+      continue;
+    }
+
+    if (char === "#" && !inSingle && !inDouble) {
+      const previous = index > 0 ? input[index - 1] : " ";
+      if (/\s/.test(previous)) {
+        return input.slice(0, index).trimEnd();
+      }
+    }
+  }
+
+  return input.trimEnd();
+}
+
+function splitTopLevel(value, delimiter) {
+  const input = String(value);
+  const parts = [];
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+  let braceDepth = 0;
+  let bracketDepth = 0;
+  let parenDepth = 0;
+  let last = 0;
+
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (char === "\\" && inDouble) {
+      escaped = true;
+      continue;
+    }
+
+    if (char === "'" && !inDouble) {
+      if (inSingle && input[index + 1] === "'") {
+        index += 1;
+        continue;
+      }
+      inSingle = !inSingle;
+      continue;
+    }
+
+    if (char === '"' && !inSingle) {
+      inDouble = !inDouble;
+      continue;
+    }
+
+    if (inSingle || inDouble) {
+      continue;
+    }
+
+    if (char === "{") {
+      braceDepth += 1;
+      continue;
+    }
+    if (char === "}") {
+      braceDepth = Math.max(0, braceDepth - 1);
+      continue;
+    }
+    if (char === "[") {
+      bracketDepth += 1;
+      continue;
+    }
+    if (char === "]") {
+      bracketDepth = Math.max(0, bracketDepth - 1);
+      continue;
+    }
+    if (char === "(") {
+      parenDepth += 1;
+      continue;
+    }
+    if (char === ")") {
+      parenDepth = Math.max(0, parenDepth - 1);
+      continue;
+    }
+
+    if (char === delimiter && braceDepth === 0 && bracketDepth === 0 && parenDepth === 0) {
+      parts.push(input.slice(last, index));
+      last = index + 1;
+    }
+  }
+
+  parts.push(input.slice(last));
+  return parts;
+}
+
+function splitKeyValueLine(line, options) {
+  const opts = options || {};
+  const input = String(line);
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (char === "\\" && inDouble) {
+      escaped = true;
+      continue;
+    }
+
+    if (char === "'" && !inDouble) {
+      if (inSingle && input[index + 1] === "'") {
+        index += 1;
+        continue;
+      }
+      inSingle = !inSingle;
+      continue;
+    }
+
+    if (char === '"' && !inSingle) {
+      inDouble = !inDouble;
+      continue;
+    }
+
+    if (char === ":" && !inSingle && !inDouble) {
+      const next = input[index + 1];
+      if (!opts.allowTightValue && typeof next !== "undefined" && !/\s/.test(next)) {
+        continue;
+      }
+      const key = stripQuotes(input.slice(0, index).trim());
+      if (!key) {
+        return null;
+      }
+      return [key, input.slice(index + 1)];
+    }
+  }
+
+  return null;
+}
+
+function parseInlineCollection(value) {
+  const input = String(value).trim();
+  if (input.startsWith("{") && input.endsWith("}")) {
+    const inner = input.slice(1, -1).trim();
+    if (!inner) {
+      return {};
+    }
+
+    const result = {};
+    for (const entry of splitTopLevel(inner, ",")) {
+      const item = entry.trim();
+      if (!item) {
+        continue;
+      }
+
+      const pair = splitKeyValueLine(item, { allowTightValue: true });
+      if (!pair) {
+        return undefined;
+      }
+      result[pair[0]] = parseScalar(pair[1]);
+    }
+    return result;
+  }
+
+  if (input.startsWith("[") && input.endsWith("]")) {
+    const inner = input.slice(1, -1).trim();
+    if (!inner) {
+      return [];
+    }
+    return splitTopLevel(inner, ",").map((item) => parseScalar(item.trim()));
+  }
+
+  return undefined;
+}
+
+function isBlockScalarIndicator(value) {
+  const cleaned = stripInlineComment(value).trim();
+  return /^[|>][-+]?$/.test(cleaned);
+}
+
+function foldBlockLines(lines) {
+  let output = "";
+  for (const line of lines) {
+    if (line === "") {
+      output += "\n";
+      continue;
+    }
+    if (output === "" || output.endsWith("\n")) {
+      output += line;
+    } else {
+      output += ` ${line}`;
+    }
+  }
+  return output;
+}
+
+function parseBlockScalar(lines, startIndex, baseIndent, indicator) {
+  const style = String(indicator).trim().startsWith(">") ? ">" : "|";
+  const rawBlock = [];
+  let minIndent = Infinity;
+  let index = startIndex + 1;
+
+  while (index < lines.length) {
+    const rawLine = lines[index];
+    const trimmed = rawLine.trim();
+    if (!trimmed) {
+      rawBlock.push("");
+      index += 1;
+      continue;
+    }
+
+    const indent = rawLine.match(/^ */)[0].length;
+    if (indent <= baseIndent) {
+      break;
+    }
+
+    minIndent = Math.min(minIndent, indent);
+    rawBlock.push(rawLine);
+    index += 1;
+  }
+
+  if (rawBlock.length === 0) {
+    return { value: "", nextIndex: startIndex };
+  }
+
+  const normalized = rawBlock.map((line) => {
+    if (!line) {
+      return "";
+    }
+    return line.slice(Math.min(minIndent, line.match(/^ */)[0].length));
+  });
+
+  const value = style === ">" ? foldBlockLines(normalized) : normalized.join("\n");
+  return { value: value.trimEnd(), nextIndex: index - 1 };
+}
+
 function parseScalar(value) {
-  const cleaned = stripQuotes(value);
+  const withoutComment = stripInlineComment(value).trim();
+  if (!withoutComment) {
+    return "";
+  }
+
+  const inlineCollection = parseInlineCollection(withoutComment);
+  if (typeof inlineCollection !== "undefined") {
+    return inlineCollection;
+  }
+
+  const cleaned = stripQuotes(withoutComment);
   if (/^(true|false)$/i.test(cleaned)) {
     return cleaned.toLowerCase() === "true";
   }
@@ -88,8 +377,10 @@ function parseRulesText(text) {
   let section = null;
   let nested = null;
   let currentTarget = null;
+  let targetEntryIndent = null;
 
-  for (const rawLine of lines) {
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    const rawLine = lines[lineIndex];
     if (!rawLine.trim() || rawLine.trim().startsWith("#")) {
       continue;
     }
@@ -100,14 +391,15 @@ function parseRulesText(text) {
     if (indent === 0) {
       nested = null;
       currentTarget = null;
+      targetEntryIndent = null;
 
-      const top = line.match(/^([a-zA-Z0-9_-]+):(.*)$/);
+      const top = splitKeyValueLine(line);
       if (!top) {
         continue;
       }
 
-      const key = top[1];
-      const value = top[2].trim();
+      const key = top[0];
+      const value = stripInlineComment(top[1]).trim();
 
       if (!value) {
         section = key;
@@ -118,7 +410,13 @@ function parseRulesText(text) {
         }
       } else {
         section = null;
-        data[key] = parseScalar(value);
+        if (isBlockScalarIndicator(value)) {
+          const parsedBlock = parseBlockScalar(lines, lineIndex, indent, value);
+          data[key] = parsedBlock.value;
+          lineIndex = parsedBlock.nextIndex;
+        } else {
+          data[key] = parseScalar(value);
+        }
       }
       continue;
     }
@@ -129,20 +427,22 @@ function parseRulesText(text) {
     }
 
     if (section === "commands") {
-      const pair = line.match(/^([a-zA-Z0-9_-]+):(.*)$/);
+      const pair = splitKeyValueLine(line);
       if (pair) {
-        data.commands[pair[1]] = parseScalar(pair[2].trim());
+        data.commands[pair[0]] = parseScalar(pair[1]);
       }
       continue;
     }
 
     if (section === "approvals") {
-      if (line.startsWith("mode:")) {
-        data.approvals.mode = parseScalar(line.slice("mode:".length).trim());
+      const pair = splitKeyValueLine(line);
+
+      if (pair && pair[0] === "mode") {
+        data.approvals.mode = parseScalar(pair[1]);
         continue;
       }
 
-      if (line === "notes:") {
+      if (pair && pair[0] === "notes" && !stripInlineComment(pair[1]).trim()) {
         nested = "notes";
         if (!Array.isArray(data.approvals.notes)) {
           data.approvals.notes = [];
@@ -157,14 +457,20 @@ function parseRulesText(text) {
     }
 
     if (section === "targets") {
-      if (indent === 2) {
-        const target = line.match(/^([a-zA-Z0-9_-]+):(.*)$/);
-        if (!target) {
-          continue;
-        }
+      const pair = splitKeyValueLine(line);
+      if (!pair) {
+        continue;
+      }
+
+      const key = pair[0];
+      const maybeValue = stripInlineComment(pair[1]).trim();
+
+      if (targetEntryIndent === null) {
+        targetEntryIndent = indent;
+      }
 
-        currentTarget = target[1];
-        const maybeValue = target[2].trim();
+      if (indent === targetEntryIndent) {
+        currentTarget = key;
         if (!maybeValue) {
           data.targets[currentTarget] = {};
         } else {
@@ -173,14 +479,11 @@ function parseRulesText(text) {
         continue;
       }
 
-      if (indent >= 4 && currentTarget) {
-        const pair = line.match(/^([a-zA-Z0-9_-]+):(.*)$/);
-        if (pair) {
-          if (!data.targets[currentTarget] || typeof data.targets[currentTarget] !== "object") {
-            data.targets[currentTarget] = {};
-          }
-          data.targets[currentTarget][pair[1]] = parseScalar(pair[2].trim());
+      if (indent > targetEntryIndent && currentTarget) {
+        if (!data.targets[currentTarget] || typeof data.targets[currentTarget] !== "object") {
+          data.targets[currentTarget] = {};
         }
+        data.targets[currentTarget][key] = parseScalar(maybeValue);
       }
     }
   }
@@ -272,10 +575,31 @@ function normalizeRules(input, defaults) {
   const notes = Array.isArray(approvals.notes)
     ? approvals.notes.filter((item) => typeof item === "string")
     : defaults.approvals.notes;
+  const normalizedCommands = {};
+  for (const [name, value] of Object.entries(commands)) {
+    const normalizedName = String(name).trim();
+    if (!normalizedName || typeof value !== "string" || !value.trim()) {
+      continue;
+    }
+    normalizedCommands[normalizedName] = value.trim();
+  }
+
+  for (const required of ["lint", "test", "build"]) {
+    if (!normalizedCommands[required] && defaults.commands[required]) {
+      normalizedCommands[required] = defaults.commands[required];
+    }
+  }
 
   const targets = {};
   for (const adapter of ADAPTERS) {
-    targets[adapter.id] = normalizeTargetConfig(sourceTargets[adapter.id], defaults.targets[adapter.id].path);
+    const fallback = defaults.targets[adapter.id]
+      ? defaults.targets[adapter.id].path
+      : adapter.defaultPath;
+    const config = normalizeTargetConfig(sourceTargets[adapter.id], fallback);
+    targets[adapter.id] = {
+      enabled: typeof config.enabled === "boolean" ? config.enabled : true,
+      path: config.path,
+    };
   }
 
   for (const customId of Object.keys(sourceTargets)) {
@@ -290,11 +614,7 @@ function normalizeRules(input, defaults) {
     mission:
       typeof source.mission === "string" && source.mission.trim() ? source.mission : defaults.mission,
     workflow: workflow.length > 0 ? workflow : defaults.workflow,
-    commands: {
-      lint: typeof commands.lint === "string" ? commands.lint : defaults.commands.lint,
-      test: typeof commands.test === "string" ? commands.test : defaults.commands.test,
-      build: typeof commands.build === "string" ? commands.build : defaults.commands.build,
-    },
+    commands: normalizedCommands,
     done: done.length > 0 ? done : defaults.done,
     approvals: {
       mode: typeof approvals.mode === "string" ? approvals.mode : defaults.approvals.mode,
@@ -304,6 +624,190 @@ function normalizeRules(input, defaults) {
   };
 }
 
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function getSuspiciousRuleLines(text) {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const suspicious = [];
+  let blockBaseIndent = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const indent = line.match(/^ */)[0].length;
+    const trimmed = line.trim();
+
+    if (blockBaseIndent !== null) {
+      if (!trimmed) {
+        continue;
+      }
+      if (indent > blockBaseIndent) {
+        continue;
+      }
+      blockBaseIndent = null;
+    }
+
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    const pair = splitKeyValueLine(trimmed, { allowTightValue: true });
+    if (pair) {
+      if (isBlockScalarIndicator(pair[1])) {
+        blockBaseIndent = indent;
+      }
+      continue;
+    }
+
+    if (/^-\s+/.test(trimmed)) {
+      continue;
+    }
+
+    suspicious.push(index + 1);
+  }
+  return suspicious;
+}
+
+function validateRulesSource(source, rawText) {
+  const warnings = [];
+  const errors = [];
+
+  if (!isPlainObject(source)) {
+    errors.push("Top-level YAML must be an object.");
+    return { warnings, errors };
+  }
+
+  const keys = Object.keys(source);
+  const nonCommentLines = rawText
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .filter((line) => line.trim() && !line.trim().startsWith("#"));
+  if (keys.length === 0 && nonCommentLines.length > 0) {
+    errors.push("No parseable keys found. Check YAML syntax and indentation.");
+  }
+
+  for (const key of REQUIRED_RULE_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(source, key)) {
+      warnings.push(`Missing "${key}" key; defaults will be applied.`);
+    }
+  }
+
+  const suspiciousLines = getSuspiciousRuleLines(rawText);
+  if (suspiciousLines.length > 0) {
+    warnings.push(
+      `Suspicious YAML line(s): ${suspiciousLines.slice(0, 8).join(", ")}${
+        suspiciousLines.length > 8 ? ", ..." : ""
+      }`,
+    );
+  }
+
+  if (Object.prototype.hasOwnProperty.call(source, "version") && typeof source.version !== "number") {
+    errors.push(`"version" must be a number.`);
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(source, "mission") &&
+    (typeof source.mission !== "string" || !source.mission.trim())
+  ) {
+    errors.push(`"mission" must be a non-empty string.`);
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(source, "workflow") &&
+    (!Array.isArray(source.workflow) || source.workflow.some((item) => typeof item !== "string"))
+  ) {
+    errors.push(`"workflow" must be an array of strings.`);
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(source, "done") &&
+    (!Array.isArray(source.done) || source.done.some((item) => typeof item !== "string"))
+  ) {
+    errors.push(`"done" must be an array of strings.`);
+  }
+
+  if (Object.prototype.hasOwnProperty.call(source, "commands")) {
+    if (!isPlainObject(source.commands)) {
+      errors.push(`"commands" must be an object.`);
+    } else {
+      for (const [name, value] of Object.entries(source.commands)) {
+        if (typeof value !== "string" || !value.trim()) {
+          errors.push(`"commands.${name}" must be a non-empty string.`);
+        }
+      }
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(source, "approvals")) {
+    if (!isPlainObject(source.approvals)) {
+      errors.push(`"approvals" must be an object.`);
+    } else {
+      if (
+        Object.prototype.hasOwnProperty.call(source.approvals, "mode") &&
+        (typeof source.approvals.mode !== "string" || !source.approvals.mode.trim())
+      ) {
+        errors.push(`"approvals.mode" must be a non-empty string.`);
+      }
+      if (
+        Object.prototype.hasOwnProperty.call(source.approvals, "notes") &&
+        (!Array.isArray(source.approvals.notes) ||
+          source.approvals.notes.some((item) => typeof item !== "string"))
+      ) {
+        errors.push(`"approvals.notes" must be an array of strings.`);
+      }
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(source, "targets")) {
+    if (!isPlainObject(source.targets)) {
+      errors.push(`"targets" must be an object.`);
+    } else {
+      for (const [targetId, config] of Object.entries(source.targets)) {
+        if (typeof config === "string") {
+          if (!config.trim()) {
+            errors.push(`"targets.${targetId}" must not be empty.`);
+          }
+          continue;
+        }
+        if (!isPlainObject(config)) {
+          errors.push(`"targets.${targetId}" must be a string or object.`);
+          continue;
+        }
+        if (
+          Object.prototype.hasOwnProperty.call(config, "enabled") &&
+          typeof config.enabled !== "boolean"
+        ) {
+          errors.push(`"targets.${targetId}.enabled" must be boolean.`);
+        }
+        if (Object.prototype.hasOwnProperty.call(config, "path")) {
+          if (typeof config.path !== "string" || !config.path.trim()) {
+            errors.push(`"targets.${targetId}.path" must be a non-empty string.`);
+          }
+        } else {
+          warnings.push(`"targets.${targetId}" has no "path"; default path will be used.`);
+        }
+      }
+    }
+  }
+
+  return { warnings, errors };
+}
+
+function formatValidationMessages(validation) {
+  const lines = [];
+  if (validation.errors.length > 0) {
+    lines.push("rules.yaml validation errors:");
+    for (const error of validation.errors) {
+      lines.push(`- ${error}`);
+    }
+  }
+  if (validation.warnings.length > 0) {
+    lines.push("rules.yaml validation warnings:");
+    for (const warning of validation.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 function stringifyRules(rules) {
   const knownTargetIds = ADAPTERS.map((adapter) => adapter.id);
   const allTargetIds = [
@@ -313,13 +817,19 @@ function stringifyRules(rules) {
       .sort(),
   ];
 
+  const commandNames = Object.keys(rules.commands || {});
+  const orderedCommandNames = [
+    ...["lint", "test", "build"].filter((name) => commandNames.includes(name)),
+    ...commandNames.filter((name) => !["lint", "test", "build"].includes(name)).sort(),
+  ];
+
   const lines = [
     `version: ${quoteYaml(Number.isFinite(rules.version) ? rules.version : 2)}`,
     `mission: ${quoteYaml(rules.mission)}`,
     "workflow:",
     ...rules.workflow.map((step) => `  - ${quoteYaml(step)}`),
     "commands:",
-    ...Object.keys(rules.commands).map((name) => `  ${name}: ${quoteYaml(rules.commands[name])}`),
+    ...orderedCommandNames.map((name) => `  ${name}: ${quoteYaml(rules.commands[name])}`),
     "done:",
     ...rules.done.map((item) => `  - ${quoteYaml(item)}`),
     "approvals:",
@@ -340,33 +850,44 @@ function stringifyRules(rules) {
   return lines.join("\n");
 }
 
-function hasVerifyCommand(text) {
-  return /\b(npm run|pnpm|yarn|bun)\s+(lint|test|build)\b/i.test(text);
-}
+function resolveInRoot(rootDir, filePath) {
+  if (typeof filePath !== "string" || !filePath.trim()) {
+    throw new Error("Target path must be a non-empty string.");
+  }
 
-function hasNoApprovalLanguage(text) {
-  return /never ask (for )?approval|no approvals|without approval|do not ask for approval/i.test(
-    text,
-  );
-}
+  const trimmedPath = filePath.trim();
+  if (isAbsolute(trimmedPath)) {
+    throw new Error(`Target path must be project-relative: ${trimmedPath}`);
+  }
 
-function hasAskApprovalLanguage(text) {
-  return /ask for approval|request approval|require approval|needs approval/i.test(text);
-}
+  const resolvedPath = resolve(rootDir, trimmedPath);
+  const rel = relative(rootDir, resolvedPath);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(`Target path escapes project root: ${trimmedPath}`);
+  }
 
-function hasRequireTestsLanguage(text) {
-  return /must run tests|always run tests|run tests before done/i.test(text);
+  return resolvedPath;
 }
 
-function hasSkipTestsLanguage(text) {
-  return /skip tests|tests optional|do not run tests/i.test(text);
-}
+function assertNoSymlinkTraversal(rootDir, targetPath) {
+  const rel = relative(rootDir, targetPath);
+  if (!rel || rel === ".") {
+    return;
+  }
 
-function resolveInRoot(rootDir, filePath) {
-  if (isAbsolute(filePath)) {
-    return filePath;
+  const segments = rel.split(/[/\\]+/).filter(Boolean);
+  let cursor = rootDir;
+  for (const segment of segments) {
+    cursor = resolve(cursor, segment);
+    if (!existsSync(cursor)) {
+      continue;
+    }
+    const stats = lstatSync(cursor);
+    if (stats.isSymbolicLink()) {
+      const display = relative(rootDir, cursor) || ".";
+      throw new Error(`Refusing symlink path for managed output: ${display}`);
+    }
   }
-  return resolve(rootDir, filePath);
 }
 
 function findProjectRoot(startDir) {
@@ -390,19 +911,112 @@ function ensureParentDirectory(filePath) {
   mkdirSync(dirname(filePath), { recursive: true });
 }
 
-function upsertManagedSection(existing, content, beginMarker, endMarker) {
-  const start = existing.indexOf(beginMarker);
-  const end = start >= 0 ? existing.indexOf(endMarker, start) : -1;
+function countOccurrences(text, needle) {
+  if (!needle) {
+    return 0;
+  }
+  let count = 0;
+  let cursor = 0;
+  while (true) {
+    const index = text.indexOf(needle, cursor);
+    if (index < 0) {
+      return count;
+    }
+    count += 1;
+    cursor = index + needle.length;
+  }
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function inspectMarkerBlock(text, beginMarker, endMarker) {
+  const beginCount = countOccurrences(text, beginMarker);
+  const endCount = countOccurrences(text, endMarker);
+  const firstBegin = text.indexOf(beginMarker);
+  const firstEnd = text.indexOf(endMarker);
+
+  if (beginCount === 0 && endCount === 0) {
+    return { status: "missing", beginCount, endCount, firstBegin, firstEnd };
+  }
+  if (beginCount === 1 && endCount === 1 && firstBegin >= 0 && firstEnd > firstBegin) {
+    return { status: "valid", beginCount, endCount, firstBegin, firstEnd };
+  }
+  if (beginCount === 1 && endCount === 0) {
+    return { status: "missing-end", beginCount, endCount, firstBegin, firstEnd };
+  }
+  if (beginCount === 0 && endCount === 1) {
+    return { status: "missing-begin", beginCount, endCount, firstBegin, firstEnd };
+  }
+  if (firstBegin >= 0 && firstEnd >= 0 && firstEnd < firstBegin) {
+    return { status: "misordered", beginCount, endCount, firstBegin, firstEnd };
+  }
+  return { status: "multiple", beginCount, endCount, firstBegin, firstEnd };
+}
+
+function markerStatusIssueLabel(status) {
+  if (status === "missing") {
+    return "marker block is missing.";
+  }
+  if (status === "missing-end") {
+    return "marker block is malformed (missing end marker).";
+  }
+  if (status === "missing-begin") {
+    return "marker block is malformed (missing begin marker).";
+  }
+  if (status === "misordered") {
+    return "marker block is malformed (end marker appears before begin marker).";
+  }
+  if (status === "multiple") {
+    return "marker block is malformed (multiple marker blocks detected).";
+  }
+  return "marker block state is unknown.";
+}
+
+function removeMarkerLines(text, beginMarker, endMarker) {
+  return text
+    .split("\n")
+    .filter((line) => {
+      const trimmed = line.trim();
+      return trimmed !== beginMarker && trimmed !== endMarker;
+    })
+    .join("\n");
+}
+
+function cleanMalformedMarkerContent(existing, beginMarker, endMarker, inspection) {
+  if (inspection.status === "missing-end" && inspection.firstBegin >= 0) {
+    return existing.slice(0, inspection.firstBegin).trimEnd();
+  }
+
+  let cleaned = existing;
+  const beginPattern = escapeRegExp(beginMarker);
+  const endPattern = escapeRegExp(endMarker);
+  const sectionPattern = new RegExp(`${beginPattern}[\\s\\S]*?${endPattern}\\n?`, "g");
+  cleaned = cleaned.replace(sectionPattern, "");
+  cleaned = removeMarkerLines(cleaned, beginMarker, endMarker);
+  return cleaned.trimEnd();
+}
 
-  if (start >= 0 && end > start) {
-    const before = existing.slice(0, start + beginMarker.length);
-    const after = existing.slice(end);
+function upsertManagedSection(existing, content, beginMarker, endMarker) {
+  const inspection = inspectMarkerBlock(existing, beginMarker, endMarker);
+  if (inspection.status === "valid") {
+    const before = existing.slice(0, inspection.firstBegin + beginMarker.length);
+    const after = existing.slice(inspection.firstEnd);
     return `${before}\n${content.trim()}\n${after}`.replace(/\n{3,}/g, "\n\n");
   }
 
-  const base = existing.trimEnd();
+  const managedBlock = `${beginMarker}\n${content.trim()}\n${endMarker}\n`;
+  if (inspection.status === "missing") {
+    const base = existing.trimEnd();
+    const prefix = base ? `${base}\n\n` : "";
+    return `${prefix}${managedBlock}`;
+  }
+
+  const cleaned = cleanMalformedMarkerContent(existing, beginMarker, endMarker, inspection);
+  const base = cleaned.trimEnd();
   const prefix = base ? `${base}\n\n` : "";
-  return `${prefix}${beginMarker}\n${content.trim()}\n${endMarker}\n`;
+  return `${prefix}${managedBlock}`;
 }
 
 function loadPackageScripts(rootDir) {
@@ -414,25 +1028,27 @@ function loadPackageScripts(rootDir) {
 }
 
 function loadRules(rootDir, options) {
+  const opts = options || {};
   const rulesFile = resolve(rootDir, RULES_RELATIVE_PATH);
   const defaults = createDefaultRules(loadPackageScripts(rootDir));
 
   if (!existsSync(rulesFile)) {
-    if (options && options.allowMissing) {
-      return {
-        rules: defaults,
-        rulesFile,
-        rulesExists: false,
-      };
-    }
     throw new Error(`Missing ${rulesFile}. Run "rules-doctor init" to create it first.`);
   }
 
-  const parsed = parseRulesText(readFileSync(rulesFile, "utf8"));
+  const rawText = readFileSync(rulesFile, "utf8");
+  const parsed = parseRulesText(rawText);
+  const validation = validateRulesSource(parsed, rawText);
+  if (validation.errors.length > 0) {
+    throw new Error(formatValidationMessages(validation));
+  }
+  if (validation.warnings.length > 0 && opts.logger && typeof opts.logger.log === "function") {
+    opts.logger.log(formatValidationMessages(validation));
+  }
+
   return {
     rules: normalizeRules(parsed, defaults),
     rulesFile,
-    rulesExists: true,
   };
 }
 
@@ -464,204 +1080,633 @@ function getTargetsFromSpec(spec) {
   return unique;
 }
 
-function parseSyncTargets(args) {
-  if (!args || args.length === 0) {
-    return ADAPTERS.map((adapter) => adapter.id);
+function parseInitArgs(args) {
+  const options = {
+    importExisting: false,
+  };
+
+  for (let index = 0; index < (args || []).length; index += 1) {
+    const arg = args[index];
+    if (arg === "--import") {
+      options.importExisting = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option for init: ${arg}`);
   }
 
-  let targetSpec = "all";
-  for (let index = 0; index < args.length; index += 1) {
+  return options;
+}
+
+function parseTargetedArgs(commandName, args, extra) {
+  const options = {
+    targetSpec: "all",
+    diff: false,
+    write: false,
+    backup: false,
+  };
+  const allowed = extra || {};
+
+  for (let index = 0; index < (args || []).length; index += 1) {
     const arg = args[index];
     if (arg === "--target") {
       const value = args[index + 1];
       if (!value) {
-        throw new Error("Missing value for --target");
+        throw new Error(`Missing value for --target (${commandName})`);
       }
-      targetSpec = value;
+      options.targetSpec = value;
       index += 1;
       continue;
     }
+    if (arg === "--diff") {
+      options.diff = true;
+      continue;
+    }
+    if (arg === "--write" && allowed.write) {
+      options.write = true;
+      continue;
+    }
+    if (arg === "--backup" && allowed.backup) {
+      options.backup = true;
+      continue;
+    }
+    throw new Error(`Unknown option for ${commandName}: ${arg}`);
+  }
 
-    throw new Error(`Unknown option for sync: ${arg}`);
+  if (options.backup && !options.write) {
+    throw new Error("--backup requires --write.");
   }
 
-  return getTargetsFromSpec(targetSpec);
+  return {
+    targetIds: getTargetsFromSpec(options.targetSpec),
+    diff: options.diff,
+    write: options.write,
+    backup: options.backup,
+  };
 }
 
-function parseAnalyzeArgs(args) {
-  if (!args || args.length === 0) {
-    return {};
+function getTargetConfig(rules, adapter) {
+  const source = rules.targets && typeof rules.targets === "object" ? rules.targets[adapter.id] : null;
+  return normalizeTargetConfig(source, adapter.defaultPath);
+}
+
+function normalizeHeading(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+
+function parseMarkdownSections(text) {
+  const sections = {};
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  let currentHeading = null;
+  let currentLines = [];
+
+  function flush() {
+    if (!currentHeading) {
+      return;
+    }
+    const normalized = normalizeHeading(currentHeading);
+    if (!sections[normalized]) {
+      sections[normalized] = currentLines.join("\n").trim();
+    }
   }
 
-  for (const arg of args) {
-    if (arg === "--strict") {
-      return { strict: true };
+  for (const line of lines) {
+    const heading = line.match(/^#{1,6}\s+(.+?)\s*$/);
+    if (heading) {
+      flush();
+      currentHeading = heading[1];
+      currentLines = [];
+      continue;
+    }
+
+    if (currentHeading) {
+      currentLines.push(line);
     }
-    throw new Error(`Unknown option for analyze: ${arg}`);
   }
 
-  return {};
+  flush();
+  return sections;
 }
 
-function getTargetConfig(rules, adapter) {
-  const source = rules.targets && typeof rules.targets === "object" ? rules.targets[adapter.id] : null;
-  return normalizeTargetConfig(source, adapter.defaultPath);
+function pickFirstNonEmptyLine(text) {
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+  return "";
+}
+
+function parseListItems(text) {
+  const items = [];
+  for (const line of text.split("\n")) {
+    const bullet = line.match(/^\s*[-*]\s+(.+?)\s*$/);
+    if (bullet) {
+      items.push(bullet[1].trim());
+      continue;
+    }
+    const numbered = line.match(/^\s*\d+\.\s+(.+?)\s*$/);
+    if (numbered) {
+      items.push(numbered[1].trim());
+    }
+  }
+  return items;
+}
+
+function unquoteValue(value) {
+  let current = value.trim();
+  if (current.startsWith("`") && current.endsWith("`")) {
+    current = current.slice(1, -1);
+  }
+  current = stripQuotes(current);
+  return current.trim();
+}
+
+function importCommandsFromText(text, commands) {
+  const merged = { ...commands };
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const commandNames = Object.keys(merged);
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    for (const name of commandNames) {
+      const direct = line.match(new RegExp(`^(?:[-*]\\s*)?${name}\\s*:\\s*(.+)$`, "i"));
+      if (direct && direct[1]) {
+        merged[name] = unquoteValue(direct[1]);
+      }
+    }
+  }
+
+  for (const name of commandNames) {
+    if (!merged[name] || merged[name].includes("TODO")) {
+      const found = text.match(new RegExp(`\\b(?:npm run|pnpm|yarn|bun)\\s+${name}\\b`, "i"));
+      if (found) {
+        merged[name] = found[0];
+      }
+    }
+  }
+
+  return merged;
 }
 
-function initCommand(rootDir, logger) {
+function getSectionText(sections, aliases) {
+  for (const alias of aliases) {
+    const key = normalizeHeading(alias);
+    if (sections[key] && sections[key].trim()) {
+      return sections[key].trim();
+    }
+  }
+  return "";
+}
+
+function collectImportSources(rootDir) {
+  const candidates = [
+    { path: "CLAUDE.md" },
+    { path: ".claude/CLAUDE.md" },
+    { path: "AGENTS.md" },
+    { path: ".github/copilot-instructions.md" },
+    { path: "GEMINI.md" },
+    { path: ".cursor/rules/rules-doctor.mdc" },
+  ];
+
+  const uniquePaths = new Set();
+  const sources = [];
+
+  for (const item of candidates) {
+    if (uniquePaths.has(item.path)) {
+      continue;
+    }
+    uniquePaths.add(item.path);
+
+    const absolutePath = resolveInRoot(rootDir, item.path);
+    if (!existsSync(absolutePath)) {
+      continue;
+    }
+    sources.push({
+      path: item.path,
+      text: readFileSync(absolutePath, "utf8"),
+    });
+  }
+
+  return sources;
+}
+
+function importRulesFromDocs(rootDir, defaults) {
+  const imported = JSON.parse(JSON.stringify(defaults));
+  const sources = collectImportSources(rootDir);
+  const notes = [];
+
+  if (sources.length === 0) {
+    return {
+      rules: imported,
+      report: "No existing docs were found. Created default rules.",
+    };
+  }
+
+  notes.push(`Found ${sources.length} source file(s):`);
+  for (const source of sources) {
+    notes.push(`- ${source.path}`);
+  }
+
+  for (const source of sources) {
+    const sections = parseMarkdownSections(source.text);
+
+    const missionSection = getSectionText(sections, ["mission"]);
+    if (missionSection) {
+      const mission = pickFirstNonEmptyLine(missionSection);
+      if (mission) {
+        imported.mission = mission;
+      }
+    }
+
+    const workflowSection = getSectionText(sections, ["workflow", "operational loop"]);
+    const workflow = parseListItems(workflowSection);
+    if (workflow.length > 0) {
+      imported.workflow = workflow;
+    }
+
+    const doneSection = getSectionText(sections, ["done", "done criteria"]);
+    const done = parseListItems(doneSection);
+    if (done.length > 0) {
+      imported.done = done;
+    }
+
+    const approvalsSection = getSectionText(sections, ["approvals", "approval"]);
+    if (approvalsSection) {
+      const mode = approvalsSection.match(/(?:mode|policy)\s*:\s*`?([a-z0-9_-]+)`?/i);
+      if (mode && mode[1]) {
+        imported.approvals.mode = mode[1].trim();
+      }
+      const approvalNotes = parseListItems(approvalsSection);
+      if (approvalNotes.length > 0) {
+        imported.approvals.notes = approvalNotes;
+      }
+    }
+
+    imported.commands = importCommandsFromText(source.text, imported.commands);
+  }
+
+  for (const adapter of ADAPTERS) {
+    const config = getTargetConfig(imported, adapter);
+    const absolutePath = resolveInRoot(rootDir, config.path);
+    if (existsSync(absolutePath)) {
+      imported.targets[adapter.id].enabled = true;
+    }
+  }
+
+  notes.push("Imported mission/workflow/commands/done/approvals where detected.");
+  return {
+    rules: imported,
+    report: notes.join("\n"),
+  };
+}
+
+function initCommand(rootDir, logger, args) {
+  const options = parseInitArgs(args);
   const rulesFile = resolve(rootDir, RULES_RELATIVE_PATH);
   if (existsSync(rulesFile)) {
     logger.log(`rules.yaml already exists: ${rulesFile}`);
-    return;
+    return 0;
   }
 
   const defaults = createDefaultRules(loadPackageScripts(rootDir));
+  let rules = defaults;
+  let importReport = "";
+
+  if (options.importExisting) {
+    const imported = importRulesFromDocs(rootDir, defaults);
+    rules = imported.rules;
+    importReport = imported.report;
+  }
+
   ensureParentDirectory(rulesFile);
-  writeFileSync(rulesFile, stringifyRules(defaults), "utf8");
+  writeFileSync(rulesFile, stringifyRules(rules), "utf8");
   logger.log(`Created ${rulesFile}`);
+
+  if (options.importExisting) {
+    const reportPath = resolve(rootDir, IMPORT_REPORT_RELATIVE_PATH);
+    writeFileSync(reportPath, `${importReport}\n`, "utf8");
+    logger.log(`Import report: ${reportPath}`);
+  }
+
+  return 0;
 }
 
-function syncCommand(rootDir, logger, args) {
-  const { rules } = loadRules(rootDir);
-  const selectedTargetIds = parseSyncTargets(args);
+function buildTargetPlans(rootDir, rules, targetIds) {
+  const plans = [];
 
-  let updated = 0;
-  for (const targetId of selectedTargetIds) {
+  for (const targetId of targetIds) {
     const adapter = ADAPTERS_BY_ID[targetId];
     const target = getTargetConfig(rules, adapter);
+    const targetPath = resolveInRoot(rootDir, target.path);
+    assertNoSymlinkTraversal(rootDir, targetPath);
+    const fileExists = existsSync(targetPath);
+    const currentText = fileExists ? readFileSync(targetPath, "utf8") : "";
 
     if (!target.enabled) {
-      logger.log(`Skipped ${targetId} (disabled in rules.yaml).`);
+      plans.push({
+        targetId,
+        adapter,
+        enabled: false,
+        targetPath,
+        targetPathDisplay: target.path,
+        exists: fileExists,
+        currentText,
+        desiredText: currentText,
+        changed: false,
+      });
       continue;
     }
 
-    const targetPath = resolveInRoot(rootDir, target.path);
     const rendered = adapter.render(rules).trim();
-    ensureParentDirectory(targetPath);
-
-    if (adapter.management === "marker") {
-      const existing = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
-      const updatedText = upsertManagedSection(
-        existing,
-        rendered,
-        adapter.markerBegin,
-        adapter.markerEnd,
-      );
-      writeFileSync(targetPath, updatedText, "utf8");
-    } else {
-      writeFileSync(targetPath, `${rendered}\n`, "utf8");
-    }
+    const desiredText =
+      adapter.management === "marker"
+        ? upsertManagedSection(currentText, rendered, adapter.markerBegin, adapter.markerEnd)
+        : `${rendered}\n`;
+
+    plans.push({
+      targetId,
+      adapter,
+      enabled: true,
+      targetPath,
+      targetPathDisplay: target.path,
+      exists: fileExists,
+      currentText,
+      desiredText,
+      changed: desiredText !== currentText,
+    });
+  }
+
+  return plans;
+}
 
-    logger.log(`Updated ${targetPath} (${targetId})`);
-    updated += 1;
+function renderSimpleDiff(currentText, desiredText) {
+  if (currentText === desiredText) {
+    return "";
   }
 
-  if (updated === 0) {
-    logger.log("No files updated.");
+  const oldLines = currentText.replace(/\r\n/g, "\n").split("\n");
+  const newLines = desiredText.replace(/\r\n/g, "\n").split("\n");
+  const output = ["--- current", "+++ desired"];
+  const maxLines = Math.max(oldLines.length, newLines.length);
+  const hardLimit = 120;
+  let emitted = 0;
+
+  for (let index = 0; index < maxLines; index += 1) {
+    const oldLine = oldLines[index];
+    const newLine = newLines[index];
+
+    if (oldLine === newLine) {
+      continue;
+    }
+
+    if (typeof oldLine !== "undefined") {
+      output.push(`-${oldLine}`);
+      emitted += 1;
+    }
+    if (typeof newLine !== "undefined") {
+      output.push(`+${newLine}`);
+      emitted += 1;
+    }
+
+    if (emitted >= hardLimit) {
+      output.push("... diff truncated ...");
+      break;
+    }
   }
+
+  return output.join("\n");
 }
 
-function analyzeCommand(rootDir, logger, args) {
-  const options = parseAnalyzeArgs(args);
-  const { rules, rulesExists, rulesFile } = loadRules(rootDir, { allowMissing: true });
-  const issues = [];
-  const targetSnapshots = [];
+function formatPlanSummary(plans) {
+  const changed = plans.filter((plan) => plan.changed).length;
+  const changedFiles = new Set(plans.filter((plan) => plan.changed).map((plan) => plan.targetPath)).size;
+  return { changed, changedFiles };
+}
 
-  logger.log("rules-doctor analyze");
-  logger.log(`- rules.yaml: ${rulesExists ? "found" : "missing (using defaults)"}`);
-  logger.log(`- rules path: ${rulesFile}`);
+function analyzeSharedPathPlans(plans) {
+  const groups = new Map();
+  for (const plan of plans) {
+    if (!plan.enabled) {
+      continue;
+    }
+    if (!groups.has(plan.targetPath)) {
+      groups.set(plan.targetPath, []);
+    }
+    groups.get(plan.targetPath).push(plan);
+  }
 
-  for (const adapter of ADAPTERS) {
-    const target = getTargetConfig(rules, adapter);
-    const absolutePath = resolveInRoot(rootDir, target.path);
-    const fileExists = existsSync(absolutePath);
-    const content = fileExists ? readFileSync(absolutePath, "utf8") : "";
+  const shared = [];
+  const conflicts = [];
+  for (const plansAtPath of groups.values()) {
+    if (plansAtPath.length < 2) {
+      continue;
+    }
 
-    logger.log(
-      `- target ${adapter.id}: ${target.enabled ? "enabled" : "disabled"}, ${
-        fileExists ? "found" : "missing"
-      } (${target.path})`,
-    );
+    const ids = plansAtPath.map((plan) => plan.targetId);
+    const firstDesired = plansAtPath[0].desiredText;
+    const sameDesired = plansAtPath.every((plan) => plan.desiredText === firstDesired);
+    if (sameDesired) {
+      shared.push({
+        targetPathDisplay: plansAtPath[0].targetPathDisplay,
+        ids,
+      });
+      continue;
+    }
 
-    if (!target.enabled) {
+    conflicts.push({
+      targetPathDisplay: plansAtPath[0].targetPathDisplay,
+      ids,
+    });
+  }
+
+  return { shared, conflicts };
+}
+
+function validateSyncPlans(plans) {
+  const mapping = analyzeSharedPathPlans(plans);
+  const issues = mapping.conflicts.map(
+    (group) =>
+      `Conflicting outputs map to the same file: ${group.ids.join(", ")} -> ${group.targetPathDisplay}`,
+  );
+  const warnings = [];
+
+  for (const plan of plans) {
+    if (!plan.enabled || !plan.exists || plan.adapter.management !== "marker") {
       continue;
     }
+    const marker = inspectMarkerBlock(
+      plan.currentText,
+      plan.adapter.markerBegin,
+      plan.adapter.markerEnd,
+    );
+    if (marker.status !== "valid" && marker.status !== "missing") {
+      warnings.push(
+        `${plan.targetId}: ${markerStatusIssueLabel(marker.status)} rules-doctor will repair it on sync.`,
+      );
+    }
+  }
+
+  return { issues, warnings };
+}
+
+function getUniqueWritePlans(plans) {
+  const byPath = new Map();
+  const duplicates = [];
 
-    if (!fileExists) {
-      issues.push(`${adapter.id}: expected file is missing (${target.path}).`);
+  for (const plan of plans) {
+    if (!plan.enabled || !plan.changed) {
       continue;
     }
 
-    if (adapter.management === "marker") {
-      const hasBegin = content.includes(adapter.markerBegin);
-      const hasEnd = content.includes(adapter.markerEnd);
-      if (!hasBegin || !hasEnd) {
-        issues.push(`${adapter.id}: marker block is missing.`);
-      }
+    const existing = byPath.get(plan.targetPath);
+    if (!existing) {
+      byPath.set(plan.targetPath, plan);
+      continue;
     }
 
-    if (!hasVerifyCommand(content)) {
-      issues.push(`${adapter.id}: verify commands (lint/test/build) not detected.`);
+    if (existing.desiredText !== plan.desiredText) {
+      throw new Error(
+        `Conflicting outputs for ${plan.targetPathDisplay}: ${existing.targetId} and ${plan.targetId} produce different content.`,
+      );
     }
 
-    targetSnapshots.push({
-      id: adapter.id,
-      content,
-      asksApproval: hasAskApprovalLanguage(content),
-      noApproval: hasNoApprovalLanguage(content),
-      requiresTests: hasRequireTestsLanguage(content),
-      skipsTests: hasSkipTestsLanguage(content),
+    duplicates.push({
+      targetPathDisplay: plan.targetPathDisplay,
+      winner: existing.targetId,
+      duplicate: plan.targetId,
     });
   }
 
-  const askApprovalTargets = targetSnapshots.filter((item) => item.asksApproval).map((item) => item.id);
-  const noApprovalTargets = targetSnapshots.filter((item) => item.noApproval).map((item) => item.id);
-  if (askApprovalTargets.length > 0 && noApprovalTargets.length > 0) {
-    issues.push(
-      `Potential contradiction: approval guidance differs (${askApprovalTargets.join(
-        ", ",
-      )} vs ${noApprovalTargets.join(", ")}).`,
-    );
+  return {
+    uniquePlans: Array.from(byPath.values()),
+    duplicates,
+  };
+}
+
+function syncCommand(rootDir, logger, args) {
+  const options = parseTargetedArgs("sync", args, { write: true, backup: true });
+  const { rules } = loadRules(rootDir, { logger });
+  const plans = buildTargetPlans(rootDir, rules, options.targetIds);
+  const summary = formatPlanSummary(plans);
+
+  logger.log("rules-doctor sync");
+  logger.log(`- root: ${rootDir}`);
+  logger.log(`- selected targets: ${options.targetIds.join(", ")}`);
+  logger.log(`- mode: ${options.write ? "write" : "dry-run"}`);
+
+  for (const plan of plans) {
+    if (!plan.enabled) {
+      logger.log(`- ${plan.targetId}: disabled (${plan.targetPathDisplay})`);
+      continue;
+    }
+    if (!plan.changed) {
+      logger.log(`- ${plan.targetId}: up-to-date (${plan.targetPathDisplay})`);
+      continue;
+    }
+    logger.log(`- ${plan.targetId}: would update (${plan.targetPathDisplay})`);
   }
 
-  const requireTestsTargets = targetSnapshots
-    .filter((item) => item.requiresTests)
-    .map((item) => item.id);
-  const skipTestsTargets = targetSnapshots.filter((item) => item.skipsTests).map((item) => item.id);
-  if (requireTestsTargets.length > 0 && skipTestsTargets.length > 0) {
-    issues.push(
-      `Potential contradiction: test guidance differs (${requireTestsTargets.join(
-        ", ",
-      )} vs ${skipTestsTargets.join(", ")}).`,
-    );
+  if (options.diff) {
+    for (const plan of plans) {
+      if (!plan.enabled || !plan.changed) {
+        continue;
+      }
+      logger.log(`\n# diff: ${plan.targetId} (${plan.targetPathDisplay})`);
+      logger.log(renderSimpleDiff(plan.currentText, plan.desiredText));
+    }
+  }
+
+  if (options.write) {
+    const preflight = validateSyncPlans(plans);
+    for (const warning of preflight.warnings) {
+      logger.log(`  warning: ${warning}`);
+    }
+    if (preflight.issues.length > 0) {
+      logger.log("Sync preflight failed:");
+      for (const issue of preflight.issues) {
+        logger.log(`  - ${issue}`);
+      }
+      return 1;
+    }
+    logger.log("Sync preflight passed.");
   }
 
-  logger.log("- Findings:");
-  if (issues.length === 0) {
-    logger.log("- No obvious issues found.");
+  if (!options.write) {
+    if (summary.changed === 0) {
+      logger.log("Dry-run complete: no changes.");
+    } else {
+      logger.log(
+        `Dry-run complete: ${summary.changedFiles} file(s) would change (${summary.changed} target mappings). Re-run with --write.`,
+      );
+    }
     return 0;
   }
 
-  for (const issue of issues) {
-    logger.log(`- ${issue}`);
+  const { uniquePlans, duplicates } = getUniqueWritePlans(plans);
+  for (const duplicate of duplicates) {
+    logger.log(
+      `  note: ${duplicate.duplicate} shares output with ${duplicate.winner} at ${duplicate.targetPathDisplay}`,
+    );
   }
 
-  if (options.strict) {
-    throw new Error(`Analyze failed in strict mode with ${issues.length} issue(s).`);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  for (const plan of uniquePlans) {
+    ensureParentDirectory(plan.targetPath);
+    if (options.backup && plan.exists) {
+      const backupPath = `${plan.targetPath}.rules-doctor.bak.${timestamp}`;
+      writeFileSync(backupPath, plan.currentText, "utf8");
+      logger.log(`  backup: ${backupPath}`);
+    }
+
+    writeFileSync(plan.targetPath, plan.desiredText, "utf8");
+    logger.log(`  updated: ${plan.targetPath}`);
   }
 
+  logger.log(
+    `Write complete: ${uniquePlans.length} file(s) updated (${summary.changed} target mappings changed).`,
+  );
   return 0;
 }
 
-function targetsListCommand(logger) {
-  logger.log("Supported targets:");
-  for (const adapter of ADAPTERS) {
-    const mode = adapter.management === "marker" ? "marker-managed" : "full-managed";
-    logger.log(`- ${adapter.id}: ${adapter.name}`);
-    logger.log(`  default path: ${adapter.defaultPath}`);
-    logger.log(`  mode: ${mode}`);
-    logger.log(`  ${adapter.description}`);
+function checkCommand(rootDir, logger, args) {
+  const options = parseTargetedArgs("check", args, { write: false, backup: false });
+  const { rules } = loadRules(rootDir, { logger });
+  const plans = buildTargetPlans(rootDir, rules, options.targetIds);
+  const summary = formatPlanSummary(plans);
+
+  logger.log("rules-doctor check");
+  logger.log(`- root: ${rootDir}`);
+  logger.log(`- selected targets: ${options.targetIds.join(", ")}`);
+
+  for (const plan of plans) {
+    if (!plan.enabled) {
+      logger.log(`- ${plan.targetId}: disabled (${plan.targetPathDisplay})`);
+      continue;
+    }
+    logger.log(
+      `- ${plan.targetId}: ${plan.changed ? "drift detected" : "in sync"} (${plan.targetPathDisplay})`,
+    );
+  }
+
+  if (options.diff) {
+    for (const plan of plans) {
+      if (!plan.enabled || !plan.changed) {
+        continue;
+      }
+      logger.log(`\n# diff: ${plan.targetId} (${plan.targetPathDisplay})`);
+      logger.log(renderSimpleDiff(plan.currentText, plan.desiredText));
+    }
   }
+
+  if (summary.changed === 0) {
+    logger.log("Check complete: all selected targets are in sync.");
+    return 0;
+  }
+
+  logger.log(`Check failed: ${summary.changed} target file(s) need sync.`);
+  return 1;
 }
 
 function runCli(argv, options) {
@@ -679,25 +1724,15 @@ function runCli(argv, options) {
     }
 
     if (command === "init") {
-      initCommand(rootDir, logger);
-      return 0;
+      return initCommand(rootDir, logger, rest);
     }
 
     if (command === "sync") {
-      syncCommand(rootDir, logger, rest);
-      return 0;
+      return syncCommand(rootDir, logger, rest);
     }
 
-    if (command === "analyze") {
-      return analyzeCommand(rootDir, logger, rest);
-    }
-
-    if (command === "targets") {
-      if (rest.length === 1 && rest[0] === "list") {
-        targetsListCommand(logger);
-        return 0;
-      }
-      throw new Error('Unknown targets command. Use "rules-doctor targets list".');
+    if (command === "check") {
+      return checkCommand(rootDir, logger, rest);
     }
 
     throw new Error(`Unknown command: ${command}\n\n${usage()}`);