trackops 2.0.6 → 2.2.0

package/lib/plans.js

@@ -0,0 +1,1329 @@
+#!/usr/bin/env node
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const config = require("./config");
+
+const PLAN_REGISTRY_VERSION = 1;
+const PLAN_DOCUMENT_VERSION = 1;
+const PREVIEW_VERSION = 1;
+const SUPPORTED_ADAPTERS = ["canonical", "claude", "codex", "antigravity", "generic_markdown"];
+const PLAN_SCAN_FILE_RE = /(?:^|[\\/])(plan|plans|tasks|implementation|implementation-plan|task-plan|todo)(?:[-_.].+)?\.(md|markdown|txt|json)$/i;
+const MANAGED_FIELDS = [...config.DEFAULT_MANAGED_PLAN_FIELDS];
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function writeText(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content.replace(/\r?\n/g, "\n"), "utf8");
+}
+
+function writeJson(filePath, data) {
+  writeText(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function readJsonSafe(filePath, fallback = null) {
+  if (!filePath || !fs.existsSync(filePath)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (_error) {
+    return fallback;
+  }
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value || ""), "utf8").digest("hex");
+}
+
+function slugify(value) {
+  return String(value || "")
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+}
+
+function toList(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || "").trim()).filter(Boolean);
+  return String(value || "").split(/\r?\n|,/).map((item) => item.trim()).filter(Boolean);
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function ensureRegistry(context) {
+  fs.mkdirSync(context.paths.plansDir, { recursive: true });
+  if (!fs.existsSync(context.paths.plansRegistryFile)) {
+    writeJson(context.paths.plansRegistryFile, { version: PLAN_REGISTRY_VERSION, sources: [] });
+  }
+}
+
+function loadRegistry(contextOrRoot) {
+  const context = config.ensureContext(contextOrRoot);
+  ensureRegistry(context);
+  const registry = readJsonSafe(context.paths.plansRegistryFile, { version: PLAN_REGISTRY_VERSION, sources: [] }) || {};
+  registry.version = PLAN_REGISTRY_VERSION;
+  registry.sources = Array.isArray(registry.sources) ? registry.sources : [];
+  return registry;
+}
+
+function saveRegistry(contextOrRoot, registry) {
+  const context = config.ensureContext(contextOrRoot);
+  ensureRegistry(context);
+  const next = {
+    version: PLAN_REGISTRY_VERSION,
+    sources: Array.isArray(registry?.sources) ? registry.sources : [],
+  };
+  writeJson(context.paths.plansRegistryFile, next);
+  return next;
+}
+
+function planFiles(contextOrRoot, sourceId) {
+  const context = config.ensureContext(contextOrRoot);
+  const id = slugify(sourceId);
+  const dir = path.join(context.paths.plansDir, id);
+  return {
+    dir,
+    manifestFile: path.join(dir, "manifest.json"),
+    normalizedFile: path.join(dir, "normalized-plan.json"),
+    previewFile: path.join(dir, "preview.json"),
+    historyDir: path.join(dir, "history"),
+  };
+}
+
+function planRawFile(files, ext) {
+  const normalizedExt = String(ext || ".md").startsWith(".") ? String(ext || ".md") : `.${ext}`;
+  return path.join(files.dir, `raw${normalizedExt.toLowerCase()}`);
+}
+
+function normalizeRegistrySource(entry) {
+  return {
+    id: String(entry?.id || "").trim(),
+    title: String(entry?.title || entry?.id || "").trim(),
+    adapter: String(entry?.adapter || "unknown").trim(),
+    path: entry?.path ? String(entry.path).trim() : null,
+    status: String(entry?.status || "previewed").trim(),
+    checksum: entry?.checksum ? String(entry.checksum).trim() : null,
+    latestImportId: entry?.latestImportId ? String(entry.latestImportId).trim() : null,
+    lastImportAt: entry?.lastImportAt ? String(entry.lastImportAt).trim() : null,
+    lastPreviewAt: entry?.lastPreviewAt ? String(entry.lastPreviewAt).trim() : null,
+    lastApplyAt: entry?.lastApplyAt ? String(entry.lastApplyAt).trim() : null,
+    warnings: Number.isFinite(Number(entry?.warnings)) ? Number(entry.warnings) : 0,
+    conflicts: Number.isFinite(Number(entry?.conflicts)) ? Number(entry.conflicts) : 0,
+    managedTaskCount: Number.isFinite(Number(entry?.managedTaskCount)) ? Number(entry.managedTaskCount) : 0,
+  };
+}
+
+function upsertRegistrySource(contextOrRoot, entry) {
+  const registry = loadRegistry(contextOrRoot);
+  const normalized = normalizeRegistrySource(entry);
+  const existingIndex = registry.sources.findIndex((source) => source.id === normalized.id);
+  if (existingIndex >= 0) registry.sources[existingIndex] = normalized;
+  else registry.sources.push(normalized);
+  saveRegistry(contextOrRoot, registry);
+  return normalized;
+}
+
+function listSources(contextOrRoot) {
+  const registry = loadRegistry(contextOrRoot);
+  return registry.sources.map((source) => normalizeRegistrySource(source));
+}
+
+function syncControlPlanMeta(controlState, contextOrRoot) {
+  const sources = listSources(contextOrRoot);
+  const previous = controlState.meta?.plans || {};
+  controlState.meta = controlState.meta || {};
+  controlState.meta.plans = {
+    activeSourceId:
+      (previous.activeSourceId && sources.some((source) => source.id === previous.activeSourceId))
+        ? previous.activeSourceId
+        : sources[0]?.id || null,
+    sources: sources.map((source) => ({
+      id: source.id,
+      title: source.title,
+      adapter: source.adapter,
+      status: source.status,
+      lastPreviewAt: source.lastPreviewAt || source.lastImportAt || null,
+      lastApplyAt: source.lastApplyAt || null,
+      warnings: source.warnings || 0,
+      conflicts: source.conflicts || 0,
+      managedTaskCount: source.managedTaskCount || 0,
+    })),
+    lastImportAt: sources
+      .map((source) => source.lastImportAt || source.lastPreviewAt || "")
+      .filter(Boolean)
+      .sort()
+      .slice(-1)[0] || null,
+    unresolvedConflicts: sources.reduce((sum, source) => sum + (source.conflicts || 0), 0),
+  };
+  return controlState.meta.plans;
+}
+
+function normalizePriority(value) {
+  const match = String(value || "").trim().toUpperCase().match(/^P[0-3]$/);
+  return match ? match[0] : "P1";
+}
+
+function normalizeStatus(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) return "pending";
+  if (["pending", "todo", "to_do"].includes(normalized)) return "pending";
+  if (["in_progress", "in-progress", "doing", "active", "started"].includes(normalized)) return "in_progress";
+  if (["in_review", "in-review", "review", "qa"].includes(normalized)) return "in_review";
+  if (["blocked", "waiting", "on_hold", "on-hold"].includes(normalized)) return "blocked";
+  if (["completed", "complete", "done", "closed"].includes(normalized)) return "completed";
+  if (["cancelled", "canceled", "dropped"].includes(normalized)) return "cancelled";
+  return "pending";
+}
+
+function normalizePhase(value, fallbackText = "") {
+  const direct = String(value || "").trim().toUpperCase();
+  if (/^[OPERA]$/.test(direct)) return direct;
+  const text = `${value || ""} ${fallbackText || ""}`.toLowerCase();
+  if (/(discover|clarif|scope|problem|analysis|orquest|orchestr|alignment|define)/.test(text)) return "O";
+  if (/(prove|test|audit|research|spike|validate|verification)/.test(text)) return "P";
+  if (/(implement|build|develop|refactor|integrat|code|estructura|establish)/.test(text)) return "E";
+  if (/(refine|polish|review|docs|documentation|ux|copy|cleanup)/.test(text)) return "R";
+  if (/(autom|deploy|release|publish|ship|ci|workflow)/.test(text)) return "A";
+  return "E";
+}
+
+function normalizeTaskType(type, depth = 0) {
+  const normalized = String(type || "").trim().toLowerCase();
+  if (["epic", "task", "subtask"].includes(normalized)) return normalized;
+  if (depth <= 0) return "epic";
+  if (depth === 1) return "task";
+  return "subtask";
+}
+
+function indentWidth(value) {
+  return String(value || "").replace(/\t/g, "  ").length;
+}
+
+function firstHeading(content) {
+  const match = String(content || "").match(/^#{1,2}\s+(.+)$/m);
+  return match ? match[1].trim() : "";
+}
+
+function buildHeadingSourceAnchors(stack, lineStart) {
+  const anchors = stack.map((entry) => ({ label: entry.text, lineStart: entry.line }));
+  if (!anchors.length) anchors.push({ label: "source", lineStart });
+  return anchors;
+}
+
+function extractInlineMeta(rawText, fallbackStatus) {
+  let text = String(rawText || "").trim();
+  const meta = {
+    status: fallbackStatus || null,
+    priority: null,
+    phase: null,
+    stream: null,
+    required: true,
+    dependsOn: [],
+  };
+
+  const priorityMatch = text.match(/\[(P[0-3])\]/i);
+  if (priorityMatch) {
+    meta.priority = priorityMatch[1].toUpperCase();
+    text = text.replace(priorityMatch[0], "").trim();
+  }
+
+  const phaseMatch = text.match(/\[(?:phase\s*:?\s*)?([OPERA])\]/i);
+  if (phaseMatch) {
+    meta.phase = phaseMatch[1].toUpperCase();
+    text = text.replace(phaseMatch[0], "").trim();
+  }
+
+  const requiredMatch = text.match(/\[(required|optional)\]/i);
+  if (requiredMatch) {
+    meta.required = requiredMatch[1].toLowerCase() !== "optional";
+    text = text.replace(requiredMatch[0], "").trim();
+  }
+
+  const dependsMatch = text.match(/\bdepends(?:\s+on)?\s*:\s*([a-z0-9_,\-\s/]+)/i);
+  if (dependsMatch) {
+    meta.dependsOn = dependsMatch[1].split(/[,/]/).map((value) => value.trim()).filter(Boolean);
+    text = text.replace(dependsMatch[0], "").trim();
+  }
+
+  const streamMatch = text.match(/\bstream\s*:\s*([^|]+)$/i);
+  if (streamMatch) {
+    meta.stream = streamMatch[1].trim();
+    text = text.replace(streamMatch[0], "").trim();
+  }
+
+  text = text.replace(/\s{2,}/g, " ").trim();
+  return { title: text || rawText.trim(), meta };
+}
+
+function normalizePlanItem(rawItem, index, context = {}) {
+  const fallbackText = `${rawItem?.title || ""} ${(context.headingTrail || []).join(" ")}`.trim();
+  const itemId = String(rawItem?.id || "").trim() || `node-${index + 1}`;
+  return {
+    id: itemId,
+    parentId: rawItem?.parentId ? String(rawItem.parentId).trim() : null,
+    type: normalizeTaskType(rawItem?.type, rawItem?.depth || 0),
+    title: String(rawItem?.title || itemId).trim(),
+    summary: String(rawItem?.summary || "").trim(),
+    phase: normalizePhase(rawItem?.phase, fallbackText),
+    stream: String(rawItem?.stream || context.stream || "Planning").trim() || "Planning",
+    priority: normalizePriority(rawItem?.priority),
+    status: normalizeStatus(rawItem?.status),
+    required: rawItem?.required !== false,
+    dependsOn: toList(rawItem?.dependsOn),
+    acceptance: toList(rawItem?.acceptance),
+    warnings: toList(rawItem?.warnings),
+    sequence: Number.isFinite(Number(rawItem?.sequence)) ? Number(rawItem.sequence) : (index + 1) * 10,
+    sourceAnchors: Array.isArray(rawItem?.sourceAnchors) && rawItem.sourceAnchors.length
+      ? rawItem.sourceAnchors.map((anchor) => ({
+          label: String(anchor?.label || "source").trim(),
+          lineStart: Number.isFinite(Number(anchor?.lineStart)) ? Number(anchor.lineStart) : 1,
+        }))
+      : [{ label: "source", lineStart: 1 }],
+  };
+}
+
+function parseCanonical(filePath, content, options = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Canonical plan is not valid JSON: ${error.message}`);
+  }
+
+  if (!parsed || typeof parsed !== "object" || !parsed.plan || !Array.isArray(parsed.plan.items)) {
+    throw new Error("Canonical plan must include source metadata and plan.items[].");
+  }
+
+  const sourceTitle = String(parsed.source?.title || firstHeading(content) || path.basename(filePath)).trim();
+  const sourceId = slugify(options.sourceId || parsed.source?.id || sourceTitle || path.basename(filePath, path.extname(filePath)));
+  const adapter = SUPPORTED_ADAPTERS.includes(parsed.source?.adapter) ? parsed.source.adapter : "canonical";
+  const items = parsed.plan.items.map((item, index) => normalizePlanItem(item, index, { stream: sourceTitle }));
+
+  return {
+    normalized: {
+      version: PLAN_DOCUMENT_VERSION,
+      source: {
+        id: sourceId,
+        title: sourceTitle,
+        adapter,
+        path: path.relative(options.baseRoot || process.cwd(), filePath).replace(/\\/g, "/"),
+        checksum: sha256(content),
+        generatedAt: parsed.source?.generatedAt || nowIso(),
+      },
+      plan: {
+        summary: String(parsed.plan.summary || "").trim(),
+        items,
+      },
+    },
+    warnings: [],
+  };
+}
+
+function buildStableNodeId(parentNodeId, title, counters) {
+  const slug = slugify(title) || "node";
+  const key = `${parentNodeId || "root"}::${slug}`;
+  const next = (counters.get(key) || 0) + 1;
+  counters.set(key, next);
+  return next === 1
+    ? (parentNodeId ? `${parentNodeId}/${slug}` : slug)
+    : (parentNodeId ? `${parentNodeId}/${slug}-${next}` : `${slug}-${next}`);
+}
+
+function parseMarkdownLike(filePath, content, adapter, options = {}) {
+  const lines = String(content || "").split(/\r?\n/);
+  const warnings = [];
+  const headingStack = [];
+  const siblingCounters = new Map();
+  const listNodes = [];
+  const listStack = [];
+  let currentNode = null;
+  let summary = "";
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const rawLine = lines[i];
+    const trimmed = rawLine.trim();
+    if (!trimmed) {
+      currentNode = null;
+      continue;
+    }
+
+    const headingMatch = rawLine.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const text = headingMatch[2].trim();
+      while (headingStack.length && headingStack[headingStack.length - 1].level >= level) {
+        headingStack.pop();
+      }
+      headingStack.push({ level, text, line: i + 1 });
+      if (!summary && level <= 2 && text) summary = text;
+      currentNode = null;
+      continue;
+    }
+
+    const listMatch = rawLine.match(/^(\s*)([-*+]|\d+[.)])\s+(?:\[( |x|X)\]\s*)?(.*)$/);
+    if (listMatch) {
+      const depth = Math.max(0, Math.floor(indentWidth(listMatch[1]) / 2));
+      while (listStack.length > depth) listStack.pop();
+      const parent = listStack[listStack.length - 1] || null;
+      const checkbox = listMatch[3];
+      const fallbackStatus = checkbox && /x/i.test(checkbox) ? "completed" : "pending";
+      const parsedText = extractInlineMeta(listMatch[4], fallbackStatus);
+      const nodeId = buildStableNodeId(parent?.id || null, parsedText.title, siblingCounters);
+      const headingTrail = headingStack.map((heading) => heading.text);
+      const node = normalizePlanItem({
+        id: nodeId,
+        parentId: parent?.id || null,
+        title: parsedText.title,
+        summary: "",
+        phase: parsedText.meta.phase,
+        stream: parsedText.meta.stream || headingStack[headingStack.length - 1]?.text || "Planning",
+        priority: parsedText.meta.priority,
+        status: parsedText.meta.status || fallbackStatus,
+        required: parsedText.meta.required,
+        dependsOn: parsedText.meta.dependsOn,
+        warnings: [],
+        sourceAnchors: buildHeadingSourceAnchors(headingStack, i + 1),
+        depth,
+        type: depth === 0 ? "epic" : depth === 1 ? "task" : "subtask",
+      }, listNodes.length, { headingTrail, stream: headingStack[headingStack.length - 1]?.text || "Planning" });
+      node.sourceAnchors.push({ label: parsedText.title, lineStart: i + 1 });
+      listNodes.push(node);
+      listStack.push(node);
+      currentNode = node;
+      continue;
+    }
+
+    if (currentNode) {
+      if (/^(depends(?:\s+on)?|dependency|dependencies)\s*:/i.test(trimmed)) {
+        currentNode.dependsOn = toList(trimmed.replace(/^(depends(?:\s+on)?|dependency|dependencies)\s*:/i, ""));
+        continue;
+      }
+      if (/^(acceptance|criteria)\s*:/i.test(trimmed)) {
+        currentNode.acceptance = toList(trimmed.replace(/^(acceptance|criteria)\s*:/i, ""));
+        continue;
+      }
+      if (/^(warning|warnings|note|notes)\s*:/i.test(trimmed)) {
+        currentNode.warnings = [...(currentNode.warnings || []), trimmed.replace(/^(warning|warnings|note|notes)\s*:/i, "").trim()].filter(Boolean);
+        continue;
+      }
+      currentNode.summary = [currentNode.summary, trimmed].filter(Boolean).join(" ");
+      continue;
+    }
+
+    if (!summary) summary = trimmed;
+  }
+
+  let items = listNodes;
+  if (!items.length) {
+    const headingNodes = [];
+    const headingCounters = new Map();
+    const stack = [];
+    let activeNode = null;
+
+    for (let i = 0; i < lines.length; i += 1) {
+      const rawLine = lines[i];
+      const trimmed = rawLine.trim();
+      if (!trimmed) continue;
+      const headingMatch = rawLine.match(/^(#{1,6})\s+(.+)$/);
+      if (headingMatch) {
+        const level = headingMatch[1].length;
+        const text = headingMatch[2].trim();
+        if (level === 1) {
+          if (!summary) summary = text;
+          continue;
+        }
+        while (stack.length && stack[stack.length - 1].level >= level) stack.pop();
+        const parent = stack[stack.length - 1] || null;
+        const nodeId = buildStableNodeId(parent?.node?.id || null, text, headingCounters);
+        const node = normalizePlanItem({
+          id: nodeId,
+          parentId: parent?.node?.id || null,
+          title: text,
+          summary: "",
+          phase: null,
+          stream: parent?.node?.title || "Planning",
+          sourceAnchors: [{ label: text, lineStart: i + 1 }],
+          depth: Math.max(0, level - 2),
+          type: Math.max(0, level - 2) === 0 ? "epic" : Math.max(0, level - 2) === 1 ? "task" : "subtask",
+        }, headingNodes.length, { headingTrail: stack.map((entry) => entry.node.title), stream: parent?.node?.title || "Planning" });
+        headingNodes.push(node);
+        stack.push({ level, node });
+        activeNode = node;
+        continue;
+      }
+
+      if (activeNode) {
+        if (/^[-*+]\s+/.test(trimmed)) {
+          activeNode.acceptance = [...(activeNode.acceptance || []), trimmed.replace(/^[-*+]\s+/, "").trim()].filter(Boolean);
+        } else {
+          activeNode.summary = [activeNode.summary, trimmed].filter(Boolean).join(" ");
+        }
+      }
+    }
+    items = headingNodes;
+  }
+
+  if (!items.length) {
+    warnings.push("No task-like nodes were detected in the plan source.");
+  }
+
+  const sourceTitle = summary || firstHeading(content) || path.basename(filePath, path.extname(filePath));
+  const sourceId = slugify(options.sourceId || sourceTitle || path.basename(filePath, path.extname(filePath)));
+  return {
+    normalized: {
+      version: PLAN_DOCUMENT_VERSION,
+      source: {
+        id: sourceId,
+        title: sourceTitle,
+        adapter,
+        path: path.relative(options.baseRoot || process.cwd(), filePath).replace(/\\/g, "/"),
+        checksum: sha256(content),
+        generatedAt: nowIso(),
+      },
+      plan: {
+        summary: summary || `Imported ${items.length} items from ${path.basename(filePath)}.`,
+        items,
+      },
+    },
+    warnings,
+  };
+}
+
+function detectAdapter(filePath, content) {
+  const ext = path.extname(filePath).toLowerCase();
+  const text = String(content || "");
+  const basename = path.basename(filePath).toLowerCase();
+
+  if (ext === ".json") {
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && parsed.plan && Array.isArray(parsed.plan.items)) {
+        return { adapter: "canonical", confidence: 1, reason: "canonical-json" };
+      }
+    } catch (_error) {
+      // noop
+    }
+  }
+
+  if (basename.includes("antigravity") || /antigravity|e\.t\.a\.p\.a|etapa/i.test(text)) {
+    return { adapter: "antigravity", confidence: 0.8, reason: "vendor-marker" };
+  }
+  if (basename.includes("claude") || /claude|anthropic/i.test(text)) {
+    return { adapter: "claude", confidence: 0.8, reason: "vendor-marker" };
+  }
+  if (basename.includes("codex") || /codex|openai/i.test(text)) {
+    return { adapter: "codex", confidence: 0.75, reason: "vendor-marker" };
+  }
+  if (/\n#{1,6}\s+|\n\s*[-*+]\s+|\n\s*\d+[.)]\s+/.test(`\n${text}`) || [".md", ".markdown", ".txt"].includes(ext)) {
+    return { adapter: "generic_markdown", confidence: 0.55, reason: "markdown-structure" };
+  }
+  return { adapter: ext === ".json" ? "canonical" : "generic_markdown", confidence: 0.2, reason: "fallback" };
+}
+
+function loadAndNormalizePlan(filePath, options = {}) {
+  const baseRoot = options.baseRoot || config.ensureContext(process.cwd()).workspaceRoot;
+  const absoluteFile = path.resolve(baseRoot, filePath);
+  if (!fs.existsSync(absoluteFile)) {
+    throw new Error(`Plan file not found: ${absoluteFile}`);
+  }
+
+  const content = fs.readFileSync(absoluteFile, "utf8");
+  const detected = options.adapter && options.adapter !== "auto"
+    ? { adapter: options.adapter, confidence: 1, reason: "explicit" }
+    : detectAdapter(absoluteFile, content);
+  const adapter = detected.adapter;
+  const parsed = adapter === "canonical"
+    ? parseCanonical(absoluteFile, content, options)
+    : parseMarkdownLike(absoluteFile, content, adapter, options);
+
+  parsed.normalized.source.adapter = adapter;
+  parsed.normalized.source.path = path.relative(baseRoot, absoluteFile).replace(/\\/g, "/");
+  parsed.normalized.source.checksum = sha256(content);
+  if (options.sourceId) parsed.normalized.source.id = slugify(options.sourceId);
+  if (!parsed.normalized.source.id) {
+    parsed.normalized.source.id = slugify(parsed.normalized.source.title || path.basename(absoluteFile, path.extname(absoluteFile)));
+  }
+
+  return {
+    filePath: absoluteFile,
+    rawContent: content,
+    adapter,
+    detection: detected,
+    normalizedPlan: parsed.normalized,
+    warnings: parsed.warnings || [],
+  };
+}
+
+function normalizeFieldValue(field, value) {
+  if (field === "acceptance" || field === "dependsOn") return toList(value);
+  if (field === "required") return value !== false;
+  if (field === "parentId") return value == null ? null : String(value).trim() || null;
+  if (field === "sequence") {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : null;
+  }
+  return String(value == null ? "" : value).trim();
+}
+
+function extractManagedSnapshot(task) {
+  return {
+    title: normalizeFieldValue("title", task?.title),
+    summary: normalizeFieldValue("summary", task?.summary),
+    acceptance: normalizeFieldValue("acceptance", task?.acceptance),
+    dependsOn: normalizeFieldValue("dependsOn", task?.dependsOn),
+    phase: normalizeFieldValue("phase", task?.phase),
+    stream: normalizeFieldValue("stream", task?.stream),
+    priority: normalizeFieldValue("priority", task?.priority),
+    required: normalizeFieldValue("required", task?.required),
+    parentId: normalizeFieldValue("parentId", task?.parentId),
+    sequence: normalizeFieldValue("sequence", task?.sequence),
+  };
+}
+
+function fingerprintSnapshot(snapshot) {
+  return sha256(JSON.stringify(snapshot));
+}
+
+function diffFields(a, b, fields = MANAGED_FIELDS) {
+  return fields.filter((field) => (
+    JSON.stringify(normalizeFieldValue(field, a?.[field])) !== JSON.stringify(normalizeFieldValue(field, b?.[field]))
+  ));
+}
+
+function loadManifest(contextOrRoot, sourceId) {
+  const files = planFiles(contextOrRoot, sourceId);
+  return readJsonSafe(files.manifestFile, null);
+}
+
+function saveManifest(contextOrRoot, sourceId, manifest) {
+  const files = planFiles(contextOrRoot, sourceId);
+  writeJson(files.manifestFile, manifest);
+  return manifest;
+}
+
+function loadHistoryEntry(contextOrRoot, sourceId, importId) {
+  const files = planFiles(contextOrRoot, sourceId);
+  if (!importId) return null;
+  return readJsonSafe(path.join(files.historyDir, `${importId}.json`), null);
+}
+
+function saveHistoryEntry(contextOrRoot, sourceId, importId, payload) {
+  const files = planFiles(contextOrRoot, sourceId);
+  fs.mkdirSync(files.historyDir, { recursive: true });
+  writeJson(path.join(files.historyDir, `${importId}.json`), payload);
+}
+
+function buildExistingPlanMaps(controlState, sourceId) {
+  const byNode = new Map();
+  const byFingerprint = new Map();
+  const all = [];
+
+  (controlState.tasks || []).forEach((task) => {
+    const normalized = config.normalizeTaskShape(task);
+    all.push(normalized);
+    if (normalized.origin?.kind === "plan_import" && normalized.origin.sourceId === sourceId && normalized.origin.externalNodeId) {
+      byNode.set(normalized.origin.externalNodeId, normalized);
+      if (normalized.origin.fingerprint) {
+        if (!byFingerprint.has(normalized.origin.fingerprint)) byFingerprint.set(normalized.origin.fingerprint, []);
+        byFingerprint.get(normalized.origin.fingerprint).push(normalized);
+      }
+    }
+  });
+
+  return { byNode, byFingerprint, all };
+}
+
+function loadAppliedSnapshots(contextOrRoot, sourceId, manifest = null) {
+  const effectiveManifest = manifest || loadManifest(contextOrRoot, sourceId);
+  if (!effectiveManifest?.lastApplyImportId) return new Map();
+  const history = loadHistoryEntry(contextOrRoot, sourceId, effectiveManifest.lastApplyImportId);
+  const snapshots = history?.managedSnapshots || {};
+  return new Map(Object.entries(snapshots));
+}
+
+function makeImportedTaskId(controlState, sourceId, externalNodeId, title) {
+  const existing = new Set((controlState.tasks || []).map((task) => String(task.id || "").trim()).filter(Boolean));
+  const sourceSlug = slugify(sourceId).slice(0, 18) || "plan";
+  const nodeSlug = slugify(externalNodeId || title).slice(0, 36) || "task";
+  const base = `${sourceSlug}-${nodeSlug}`;
+  if (!existing.has(base)) return base;
+  let index = 2;
+  while (existing.has(`${base}-${index}`)) index += 1;
+  return `${base}-${index}`;
+}
+
+function buildPreview(controlState, normalizedPlan, contextOrRoot, options = {}) {
+  const sourceId = normalizedPlan.source.id;
+  const importId = options.importId || nowIso().replace(/[:.]/g, "-");
+  const manifest = loadManifest(contextOrRoot, sourceId);
+  const baselineSnapshots = loadAppliedSnapshots(contextOrRoot, sourceId, manifest);
+  const maps = buildExistingPlanMaps(controlState, sourceId);
+  const matchedTaskIds = new Set();
+  const itemMatches = new Map();
+  const planWarnings = [...(options.warnings || [])];
+
+  normalizedPlan.plan.items.forEach((item) => {
+    const desiredBare = {
+      title: item.title,
+      summary: item.summary,
+      acceptance: item.acceptance || [],
+      dependsOn: item.dependsOn || [],
+      phase: item.phase,
+      stream: item.stream,
+      priority: item.priority,
+      required: item.required !== false,
+      parentId: item.parentId,
+      sequence: item.sequence,
+    };
+    const desiredFingerprint = fingerprintSnapshot(extractManagedSnapshot(desiredBare));
+    let existing = maps.byNode.get(item.id) || null;
+    if (!existing && maps.byFingerprint.has(desiredFingerprint)) {
+      existing = maps.byFingerprint.get(desiredFingerprint).find((task) => !matchedTaskIds.has(task.id)) || null;
+    }
+    const taskId = existing?.id || makeImportedTaskId(controlState, sourceId, item.id, item.title);
+    if (existing) matchedTaskIds.add(existing.id);
+    itemMatches.set(item.id, { item, existing, taskId, desiredFingerprint });
+  });
+
+  const previewTasks = new Map();
+  normalizedPlan.plan.items.forEach((item) => {
+    const match = itemMatches.get(item.id);
+    const parentTaskId = item.parentId ? itemMatches.get(item.parentId)?.taskId || null : null;
+    const translatedDepends = (item.dependsOn || []).map((dep) => {
+      if (itemMatches.has(dep)) return itemMatches.get(dep).taskId;
+      if ((controlState.tasks || []).some((task) => task.id === dep)) return dep;
+      planWarnings.push(`Dependency '${dep}' from '${item.title}' could not be mapped to an imported node.`);
+      return dep;
+    }).filter(Boolean);
+
+    const desiredTask = {
+      id: match.taskId,
+      title: item.title,
+      phase: item.phase,
+      stream: item.stream,
+      priority: item.priority,
+      status: match.existing?.status || item.status || "pending",
+      required: item.required !== false,
+      dependsOn: translatedDepends,
+      summary: item.summary || "",
+      acceptance: item.acceptance || [],
+      history: Array.isArray(match.existing?.history) ? clone(match.existing.history) : [],
+      parentId: parentTaskId,
+      sequence: item.sequence,
+      origin: {
+        kind: "plan_import",
+        sourceId,
+        adapter: normalizedPlan.source.adapter,
+        externalNodeId: item.id,
+        importId,
+        fingerprint: "",
+        managedFields: [...MANAGED_FIELDS],
+        lastImportedAt: normalizedPlan.source.generatedAt || nowIso(),
+        detached: false,
+      },
+    };
+    if (match.existing?.blocker) desiredTask.blocker = match.existing.blocker;
+    const desiredSnapshot = extractManagedSnapshot(desiredTask);
+    desiredTask.origin.fingerprint = fingerprintSnapshot(desiredSnapshot);
+    previewTasks.set(item.id, { ...match, desiredTask, desiredSnapshot });
+  });
+
+  const operations = [];
+  let conflictCount = 0;
+  let warningCount = 0;
+
+  normalizedPlan.plan.items.forEach((item) => {
+    const entry = previewTasks.get(item.id);
+    const existing = entry.existing;
+    if (!existing) {
+      operations.push({
+        type: "create",
+        sourceId,
+        externalNodeId: item.id,
+        taskId: entry.taskId,
+        title: entry.desiredTask.title,
+        desiredTask: entry.desiredTask,
+        updatedFields: [...MANAGED_FIELDS],
+        warnings: [...item.warnings],
+      });
+      warningCount += item.warnings.length;
+      return;
+    }
+
+    const existingSnapshot = extractManagedSnapshot(existing);
+    const baselineSnapshot = baselineSnapshots.get(item.id) || null;
+    const changedFromSource = baselineSnapshot ? diffFields(baselineSnapshot, entry.desiredSnapshot) : diffFields(existingSnapshot, entry.desiredSnapshot);
+    const changedLocally = baselineSnapshot ? diffFields(baselineSnapshot, existingSnapshot) : [];
+    const conflictFields = changedFromSource.filter((field) => changedLocally.includes(field));
+    const updatedFields = diffFields(existingSnapshot, entry.desiredSnapshot);
+    let type = "noop";
+    if (conflictFields.length) type = "conflict";
+    else if (updatedFields.length === 1 && updatedFields[0] === "parentId") type = "reparent";
+    else if (updatedFields.length) type = "update";
+
+    if (type === "conflict") conflictCount += 1;
+    warningCount += item.warnings.length;
+
+    operations.push({
+      type,
+      sourceId,
+      externalNodeId: item.id,
+      taskId: existing.id,
+      title: entry.desiredTask.title,
+      desiredTask: entry.desiredTask,
+      existingTask: existing,
+      updatedFields,
+      changedFromSource,
+      changedLocally,
+      conflictFields,
+      warnings: [...item.warnings],
+    });
+  });
+
+  maps.all
+    .filter((task) => task.origin?.kind === "plan_import" && task.origin.sourceId === sourceId && !matchedTaskIds.has(task.id) && task.origin.detached !== true)
+    .forEach((task) => {
+      operations.push({
+        type: "detach",
+        sourceId,
+        externalNodeId: task.origin.externalNodeId,
+        taskId: task.id,
+        title: task.title,
+        existingTask: task,
+        updatedFields: [],
+        conflictFields: [],
+        warnings: [],
+      });
+    });
+
+  const operationCounts = operations.reduce((accumulator, operation) => {
+    accumulator[operation.type] = (accumulator[operation.type] || 0) + 1;
+    return accumulator;
+  }, { create: 0, update: 0, reparent: 0, detach: 0, noop: 0, conflict: 0 });
+
+  return {
+    version: PREVIEW_VERSION,
+    importId,
+    source: clone(normalizedPlan.source),
+    generatedAt: nowIso(),
+    summary: {
+      create: operationCounts.create || 0,
+      update: operationCounts.update || 0,
+      reparent: operationCounts.reparent || 0,
+      detach: operationCounts.detach || 0,
+      noop: operationCounts.noop || 0,
+      conflicts: conflictCount,
+      warnings: planWarnings.length + warningCount,
+      managedTaskCount: normalizedPlan.plan.items.length,
+    },
+    warnings: [...new Set(planWarnings)],
+    operations,
+  };
+}
+
+function persistImportedSource(contextOrRoot, imported, preview) {
+  const context = config.ensureContext(contextOrRoot);
+  const sourceId = imported.normalizedPlan.source.id;
+  const files = planFiles(context, sourceId);
+  const previousManifest = loadManifest(context, sourceId);
+  fs.mkdirSync(files.dir, { recursive: true });
+  const rawExt = path.extname(imported.filePath) || ".md";
+  const manifest = {
+    version: 1,
+    source: clone(imported.normalizedPlan.source),
+    latestImportId: preview.importId,
+    lastImportAt: nowIso(),
+    lastPreviewAt: preview.generatedAt,
+    lastApplyImportId: previousManifest?.lastApplyImportId || null,
+    lastApplyAt: previousManifest?.lastApplyAt || null,
+    status: preview.summary.conflicts ? "preview_blocked" : "previewed",
+  };
+
+  writeText(planRawFile(files, rawExt), imported.rawContent);
+  writeJson(files.normalizedFile, imported.normalizedPlan);
+  writeJson(files.previewFile, preview);
+  saveManifest(context, sourceId, manifest);
+  saveHistoryEntry(context, sourceId, preview.importId, {
+    version: 1,
+    importedAt: preview.generatedAt,
+    importId: preview.importId,
+    normalizedPlan: imported.normalizedPlan,
+    preview,
+    managedSnapshots: Object.fromEntries(
+      imported.normalizedPlan.plan.items.map((item) => {
+        const operation = preview.operations.find((entry) => entry.externalNodeId === item.id);
+        return [item.id, operation?.desiredTask ? extractManagedSnapshot(operation.desiredTask) : null];
+      })
+    ),
+  });
+
+  const registrySource = upsertRegistrySource(context, {
+    id: sourceId,
+    title: imported.normalizedPlan.source.title,
+    adapter: imported.normalizedPlan.source.adapter,
+    path: imported.normalizedPlan.source.path,
+    checksum: imported.normalizedPlan.source.checksum,
+    status: manifest.status,
+    latestImportId: preview.importId,
+    lastImportAt: manifest.lastImportAt,
+    lastPreviewAt: manifest.lastPreviewAt,
+    lastApplyAt: manifest.lastApplyAt,
+    warnings: preview.summary.warnings,
+    conflicts: preview.summary.conflicts,
+    managedTaskCount: preview.summary.managedTaskCount,
+  });
+
+  return { files, manifest, registrySource };
+}
+
+function importPlan(contextOrRoot, options = {}) {
+  const context = config.ensureContext(contextOrRoot);
+  const controlState = config.loadControl(context);
+  const imported = loadAndNormalizePlan(options.file, { ...options, baseRoot: context.workspaceRoot });
+  const preview = buildPreview(controlState, imported.normalizedPlan, context, { warnings: imported.warnings });
+  const persisted = persistImportedSource(context, imported, preview);
+  syncControlPlanMeta(controlState, context);
+  config.saveControl(context, controlState);
+  return {
+    source: persisted.registrySource,
+    manifest: persisted.manifest,
+    normalizedPlan: imported.normalizedPlan,
+    preview,
+    control: controlState,
+  };
+}
+
+function loadSource(contextOrRoot, sourceId) {
+  const context = config.ensureContext(contextOrRoot);
+  const files = planFiles(context, sourceId);
+  const manifest = readJsonSafe(files.manifestFile, null);
+  if (!manifest) throw new Error(`Unknown plan source: ${sourceId}`);
+  const normalizedPlan = readJsonSafe(files.normalizedFile, null);
+  const preview = readJsonSafe(files.previewFile, null);
+  const registrySource = listSources(context).find((source) => source.id === slugify(sourceId)) || null;
+  return {
+    files,
+    manifest,
+    normalizedPlan,
+    preview,
+    source: registrySource || normalizeRegistrySource({
+      id: manifest.source?.id,
+      title: manifest.source?.title,
+      adapter: manifest.source?.adapter,
+      path: manifest.source?.path,
+      status: manifest.status,
+      latestImportId: manifest.latestImportId,
+      lastImportAt: manifest.lastImportAt,
+      lastPreviewAt: manifest.lastPreviewAt,
+      lastApplyAt: manifest.lastApplyAt,
+      warnings: preview?.summary?.warnings || 0,
+      conflicts: preview?.summary?.conflicts || 0,
+      managedTaskCount: preview?.summary?.managedTaskCount || normalizedPlan?.plan?.items?.length || 0,
+    }),
+  };
+}
+
+function applyManagedFields(targetTask, desiredTask, fields) {
+  fields.forEach((field) => {
+    targetTask[field] = clone(desiredTask[field]);
+  });
+}
+
+function applyPlan(contextOrRoot, sourceId, options = {}) {
+  const context = config.ensureContext(contextOrRoot);
+  const controlState = config.loadControl(context);
+  const source = loadSource(context, sourceId);
+  const selectedImportId = options.importId && options.importId !== "latest"
+    ? options.importId
+    : source.manifest.latestImportId;
+  const historyEntry = selectedImportId && selectedImportId !== source.manifest.latestImportId
+    ? loadHistoryEntry(context, source.source.id, selectedImportId)
+    : null;
+  const normalizedPlan = historyEntry?.normalizedPlan || source.normalizedPlan;
+  if (!normalizedPlan) throw new Error(`No normalized plan found for source '${sourceId}'.`);
+
+  const preview = buildPreview(controlState, normalizedPlan, context, {
+    importId: selectedImportId || source.preview?.importId || nowIso().replace(/[:.]/g, "-"),
+    warnings: source.preview?.warnings || [],
+  });
+
+  const conflictMode = options.conflicts || "abort";
+  if (preview.summary.conflicts > 0 && conflictMode === "abort") {
+    const fields = preview.operations
+      .filter((operation) => operation.type === "conflict")
+      .map((operation) => `${operation.taskId}: ${operation.conflictFields.join(", ")}`)
+      .join("; ");
+    throw new Error(`Plan apply blocked: unresolved conflicts detected (${fields || "managed fields"}).`);
+  }
+
+  const tasks = controlState.tasks.map((task) => config.normalizeTaskShape(task));
+  const taskMap = new Map(tasks.map((task) => [task.id, task]));
+  const removedMode = options.removed || "detach";
+
+  preview.operations.forEach((operation) => {
+    if (operation.type === "create") {
+      const created = config.normalizeTaskShape(operation.desiredTask);
+      created.history = created.history || [];
+      created.history.push({
+        at: nowIso(),
+        action: "plan_import_create",
+        note: `Imported from plan '${preview.source.title}' (${preview.source.id}).`,
+      });
+      tasks.push(created);
+      taskMap.set(created.id, created);
+      return;
+    }
+
+    if (operation.type === "detach") {
+      const task = taskMap.get(operation.taskId);
+      if (!task) return;
+      if (removedMode === "delete") {
+        tasks.splice(tasks.findIndex((entry) => entry.id === task.id), 1);
+        taskMap.delete(task.id);
+        tasks.forEach((entry) => {
+          if (entry.parentId === task.id) entry.parentId = null;
+          if (Array.isArray(entry.dependsOn)) entry.dependsOn = entry.dependsOn.filter((dep) => dep !== task.id);
+        });
+        return;
+      }
+      task.origin = task.origin || { kind: "plan_import" };
+      task.origin.detached = true;
+      task.history = task.history || [];
+      task.history.push({
+        at: nowIso(),
+        action: "detach_from_plan",
+        note: `Detached from plan '${preview.source.title}' (${preview.source.id}).`,
+      });
+      if (removedMode === "archive") task.status = "cancelled";
+      return;
+    }
+
+    const task = taskMap.get(operation.taskId);
+    if (!task) return;
+    const desired = config.normalizeTaskShape(operation.desiredTask);
+    const fieldsToApply = [...(operation.updatedFields || [])];
+
+    if (operation.type === "conflict" && conflictMode === "prefer-local") {
+      applyManagedFields(task, desired, fieldsToApply.filter((field) => !(operation.conflictFields || []).includes(field)));
+      task.history = task.history || [];
+      task.history.push({
+        at: nowIso(),
+        action: "plan_import_conflict",
+        note: `Applied plan '${preview.source.title}' with local preference on ${operation.conflictFields.join(", ")}.`,
+      });
+    } else {
+      applyManagedFields(task, desired, fieldsToApply);
+      task.history = task.history || [];
+      task.history.push({
+        at: nowIso(),
+        action: operation.type === "reparent" ? "plan_import_reparent" : "plan_import_update",
+        note: `Applied plan '${preview.source.title}' (${operation.type}).`,
+      });
+    }
+
+    task.origin = {
+      ...(task.origin || {}),
+      kind: "plan_import",
+      sourceId: preview.source.id,
+      adapter: preview.source.adapter,
+      externalNodeId: operation.externalNodeId,
+      importId: preview.importId,
+      fingerprint: desired.origin.fingerprint,
+      managedFields: [...MANAGED_FIELDS],
+      lastImportedAt: preview.generatedAt,
+      detached: false,
+    };
+  });
+
+  controlState.tasks = tasks;
+  const appliedPreview = buildPreview(controlState, normalizedPlan, context, {
+    importId: preview.importId,
+    warnings: source.preview?.warnings || [],
+  });
+  const manifest = {
+    ...(source.manifest || {}),
+    source: clone(normalizedPlan.source),
+    latestImportId: source.manifest?.latestImportId || preview.importId,
+    lastImportAt: source.manifest?.lastImportAt || preview.generatedAt,
+    lastPreviewAt: appliedPreview.generatedAt,
+    lastApplyImportId: preview.importId,
+    lastApplyAt: nowIso(),
+    status: "applied",
+  };
+
+  writeJson(source.files.previewFile, appliedPreview);
+  saveManifest(context, preview.source.id, manifest);
+  saveHistoryEntry(context, preview.source.id, preview.importId, {
+    version: 1,
+    importedAt: source.manifest?.lastImportAt || preview.generatedAt,
+    appliedAt: manifest.lastApplyAt,
+    importId: preview.importId,
+    normalizedPlan,
+    preview: appliedPreview,
+    managedSnapshots: Object.fromEntries(
+      normalizedPlan.plan.items.map((item) => {
+        const linkedTask = controlState.tasks.find((task) => task.origin?.sourceId === preview.source.id && task.origin?.externalNodeId === item.id);
+        return [item.id, linkedTask ? extractManagedSnapshot(linkedTask) : null];
+      })
+    ),
+  });
+
+  upsertRegistrySource(context, {
+    id: preview.source.id,
+    title: preview.source.title,
+    adapter: preview.source.adapter,
+    path: preview.source.path,
+    checksum: preview.source.checksum,
+    status: manifest.status,
+    latestImportId: manifest.latestImportId,
+    lastImportAt: manifest.lastImportAt,
+    lastPreviewAt: manifest.lastPreviewAt,
+    lastApplyAt: manifest.lastApplyAt,
+    warnings: appliedPreview.summary.warnings,
+    conflicts: 0,
+    managedTaskCount: appliedPreview.summary.managedTaskCount,
+  });
+  syncControlPlanMeta(controlState, context);
+  config.saveControl(context, controlState);
+  return {
+    source: listSources(context).find((entry) => entry.id === preview.source.id),
+    manifest,
+    preview: appliedPreview,
+    normalizedPlan,
+    control: controlState,
+  };
+}
+
+function unlinkSource(contextOrRoot, sourceId, options = {}) {
+  const context = config.ensureContext(contextOrRoot);
+  const controlState = config.loadControl(context);
+  const normalizedSourceId = slugify(sourceId);
+  let affectedTasks = 0;
+
+  controlState.tasks = controlState.tasks.map((task) => {
+    const normalized = config.normalizeTaskShape(task);
+    if (normalized.origin?.sourceId !== normalizedSourceId) return normalized;
+    affectedTasks += 1;
+    normalized.history = normalized.history || [];
+    normalized.history.push({
+      at: nowIso(),
+      action: "plan_unlink",
+      note: options.keepTasks
+        ? `Unlinked from plan '${normalizedSourceId}' and converted to manual task.`
+        : `Unlinked from plan '${normalizedSourceId}' and left detached.`,
+    });
+    if (options.keepTasks) {
+      normalized.origin = {
+        kind: "manual",
+        sourceId: null,
+        adapter: null,
+        externalNodeId: null,
+        importId: null,
+        fingerprint: null,
+        managedFields: [],
+        lastImportedAt: null,
+        detached: false,
+      };
+    } else {
+      normalized.origin = {
+        ...(normalized.origin || {}),
+        kind: "plan_import",
+        detached: true,
+      };
+    }
+    return normalized;
+  });
+
+  const registry = loadRegistry(context);
+  saveRegistry(context, {
+    version: PLAN_REGISTRY_VERSION,
+    sources: registry.sources.filter((entry) => entry.id !== normalizedSourceId),
+  });
+
+  syncControlPlanMeta(controlState, context);
+  config.saveControl(context, controlState);
+  return { sourceId: normalizedSourceId, affectedTasks, control: controlState };
+}
+
+function parsePlanArgs(args = []) {
+  const result = { _: [] };
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === "--file" && args[i + 1]) { result.file = args[i + 1]; i += 1; continue; }
+    if (token === "--path" && args[i + 1]) { result.path = args[i + 1]; i += 1; continue; }
+    if (token === "--adapter" && args[i + 1]) { result.adapter = args[i + 1]; i += 1; continue; }
+    if (token === "--source-id" && args[i + 1]) { result.sourceId = args[i + 1]; i += 1; continue; }
+    if (token === "--json") { result.json = true; continue; }
+    if (token === "--keep-tasks") { result.keepTasks = true; continue; }
+    if (token === "--conflicts" && args[i + 1]) { result.conflicts = args[i + 1]; i += 1; continue; }
+    if (token === "--removed" && args[i + 1]) { result.removed = args[i + 1]; i += 1; continue; }
+    if (token === "--import-id" && args[i + 1]) { result.importId = args[i + 1]; i += 1; continue; }
+    result._.push(token);
+  }
+  return result;
+}
+
+function discoverFiles(targetPath, results, options = {}, depth = 0) {
+  if (!targetPath || !fs.existsSync(targetPath)) return;
+  const stat = fs.statSync(targetPath);
+  if (stat.isFile()) {
+    if (PLAN_SCAN_FILE_RE.test(targetPath)) results.add(path.resolve(targetPath));
+    return;
+  }
+
+  const maxDepth = options.maxDepth ?? 3;
+  if (depth > maxDepth) return;
+
+  fs.readdirSync(targetPath, { withFileTypes: true }).forEach((entry) => {
+    if (entry.name === "." || entry.name === "..") return;
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith(".") && !options.includeHidden) return;
+      if (["node_modules", "app", ".git"].includes(entry.name)) return;
+      discoverFiles(path.join(targetPath, entry.name), results, options, depth + 1);
+      return;
+    }
+    const candidate = path.join(targetPath, entry.name);
+    if (PLAN_SCAN_FILE_RE.test(candidate)) results.add(path.resolve(candidate));
+  });
+}
+
+function scan(contextOrRoot, options = {}) {
+  const context = config.ensureContext(contextOrRoot);
+  const files = new Set();
+
+  if (options.path) {
+    discoverFiles(path.resolve(context.workspaceRoot, options.path), files, { maxDepth: 5, includeHidden: false });
+  } else {
+    discoverFiles(context.paths.plansDir, files, { maxDepth: 5, includeHidden: false });
+    discoverFiles(path.join(context.workspaceRoot, "docs"), files, { maxDepth: 4, includeHidden: false });
+    discoverFiles(context.workspaceRoot, files, { maxDepth: 0, includeHidden: false });
+  }
+
+  return [...files].sort().map((filePath) => {
+    const content = fs.readFileSync(filePath, "utf8");
+    const detection = detectAdapter(filePath, content);
+    return {
+      path: path.relative(context.workspaceRoot, filePath).replace(/\\/g, "/"),
+      absolutePath: filePath,
+      adapter: detection.adapter,
+      confidence: detection.confidence,
+      reason: detection.reason,
+      title: firstHeading(content) || path.basename(filePath),
+    };
+  });
+}
+
+function syncProjectArtifacts(contextOrRoot, controlState) {
+  const control = require("./control");
+  const api = control.forProject(contextOrRoot);
+  api.syncDocs(controlState);
+  api.refreshRepoRuntime({ quiet: true });
+}
+
+function cmdPlan(root, args = []) {
+  const context = config.ensureContext(root);
+  const parsed = parsePlanArgs(args.slice(1));
+  const subcommand = args[0];
+
+  if (subcommand === "scan") {
+    const candidates = scan(context, { path: parsed.path });
+    if (parsed.json) { console.log(JSON.stringify({ ok: true, candidates }, null, 2)); return; }
+    if (!candidates.length) { console.log("No plan candidates detected."); return; }
+    candidates.forEach((candidate) => {
+      console.log(`- ${candidate.path} [${candidate.adapter}] (${Math.round(candidate.confidence * 100)}%)`);
+    });
+    return;
+  }
+
+  if (subcommand === "list") {
+    const sources = listSources(context);
+    if (parsed.json) { console.log(JSON.stringify({ ok: true, sources }, null, 2)); return; }
+    if (!sources.length) { console.log("No imported plan sources."); return; }
+    sources.forEach((source) => {
+      console.log(`- ${source.id} :: ${source.title} [${source.adapter}] status=${source.status} warnings=${source.warnings} conflicts=${source.conflicts}`);
+    });
+    return;
+  }
+
+  if (subcommand === "import") {
+    if (!parsed.file) throw new Error("trackops plan import requires --file <path>.");
+    const result = importPlan(context, {
+      file: parsed.file,
+      adapter: parsed.adapter || "auto",
+      sourceId: parsed.sourceId,
+    });
+    syncProjectArtifacts(context, result.control);
+    if (parsed.json) { console.log(JSON.stringify({ ok: true, ...result }, null, 2)); return; }
+    console.log(`Imported plan '${result.source.id}' (${result.source.adapter}). Preview: create=${result.preview.summary.create}, update=${result.preview.summary.update}, conflicts=${result.preview.summary.conflicts}.`);
+    return;
+  }
+
+  if (subcommand === "show") {
+    const sourceId = parsed._[0];
+    if (!sourceId) throw new Error("trackops plan show requires <source-id>.");
+    const result = loadSource(context, sourceId);
+    if (parsed.json) { console.log(JSON.stringify({ ok: true, ...result }, null, 2)); return; }
+    console.log(`${result.source.title} [${result.source.id}]`);
+    console.log(`Adapter: ${result.source.adapter}`);
+    console.log(`Path: ${result.source.path}`);
+    console.log(`Status: ${result.source.status}`);
+    console.log(`Preview: create=${result.preview?.summary?.create || 0}, update=${result.preview?.summary?.update || 0}, conflicts=${result.preview?.summary?.conflicts || 0}`);
+    return;
+  }
+
+  if (subcommand === "apply") {
+    const sourceId = parsed._[0];
+    if (!sourceId) throw new Error("trackops plan apply requires <source-id>.");
+    const result = applyPlan(context, sourceId, {
+      importId: parsed.importId || "latest",
+      conflicts: parsed.conflicts || "abort",
+      removed: parsed.removed || "detach",
+    });
+    syncProjectArtifacts(context, result.control);
+    if (parsed.json) { console.log(JSON.stringify({ ok: true, ...result }, null, 2)); return; }
+    console.log(`Applied plan '${result.source.id}'. Managed tasks=${result.preview.summary.managedTaskCount}, conflicts=${result.preview.summary.conflicts}.`);
+    return;
+  }
+
+  if (subcommand === "unlink") {
+    const sourceId = parsed._[0];
+    if (!sourceId) throw new Error("trackops plan unlink requires <source-id>.");
+    const result = unlinkSource(context, sourceId, { keepTasks: parsed.keepTasks });
+    syncProjectArtifacts(context, result.control);
+    if (parsed.json) { console.log(JSON.stringify({ ok: true, ...result }, null, 2)); return; }
+    console.log(`Unlinked plan '${result.sourceId}'. Affected tasks=${result.affectedTasks}.`);
+    return;
+  }
+
+  console.log("trackops plan scan [--path <dir>] [--json]");
+  console.log("trackops plan import --file <path> [--adapter auto|canonical|claude|codex|antigravity] [--source-id <id>] [--json]");
+  console.log("trackops plan show <source-id> [--json]");
+  console.log("trackops plan apply <source-id> [--import-id latest] [--conflicts abort|prefer-source|prefer-local] [--removed detach|archive|delete] [--json]");
+  console.log("trackops plan list [--json]");
+  console.log("trackops plan unlink <source-id> [--keep-tasks] [--json]");
+}
+
+module.exports = {
+  MANAGED_FIELDS,
+  SUPPORTED_ADAPTERS,
+  detectAdapter,
+  loadAndNormalizePlan,
+  buildPreview,
+  importPlan,
+  applyPlan,
+  unlinkSource,
+  loadSource,
+  listSources,
+  scan,
+  syncControlPlanMeta,
+  extractManagedSnapshot,
+  cmdPlan,
+};