trackops 2.0.4 → 2.0.6

package/lib/control.js

@@ -1,24 +1,25 @@
 #!/usr/bin/env node
 
-const fs = require("fs");
-const path = require("path");
-const { spawnSync } = require("child_process");
-
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
 const config = require("./config");
 const env = require("./env");
 const { t, setLocale, getLocale } = require("./i18n");
-
-const PRIORITY_ORDER = ["P0", "P1", "P2", "P3"];
-const STATUS_ORDER = ["in_progress", "in_review", "pending", "blocked", "completed", "cancelled"];
-const STATUS_ICONS = {
-  pending: "\u23F3",
-  in_progress: "\uD83D\uDEA7",
-  in_review: "\uD83D\uDC40",
-  blocked: "\u26D4",
-  completed: "\u2705",
-  cancelled: "\uD83D\uDDD1\uFE0F",
-};
-const CHECK_ICONS = {
+const fmt = require("./cli-format");
+
+const PRIORITY_ORDER = ["P0", "P1", "P2", "P3"];
+const STATUS_ORDER = ["in_progress", "in_review", "pending", "blocked", "completed", "cancelled"];
+const STATUS_ICONS = {
+  pending: "\u23F3",
+  in_progress: "\uD83D\uDEA7",
+  in_review: "\uD83D\uDC40",
+  blocked: "\u26D4",
+  completed: "\u2705",
+  cancelled: "\uD83D\uDDD1\uFE0F",
+};
+const CHECK_ICONS = {
   pass: "\u2705",
   warn: "\u26A0\uFE0F",
   fail: "\u274C",
@@ -39,29 +40,79 @@ function nowIso() {
   return new Date().toISOString();
 }
 
-function git(args, root) {
-  const result = spawnSync("git", args, { cwd: root, encoding: "utf8" });
-  if (result.error || result.status !== 0) return null;
-  return result.stdout.replace(/\s+$/, "");
-}
-
-function statusLabel(status) {
-  return t(`status.${status}`);
-}
-
-/* ── repo snapshot ── */
-
+function git(args, root) {
+  const result = spawnSync("git", args, { cwd: root, encoding: "utf8" });
+  if (result.error || result.status !== 0) return null;
+  return result.stdout.replace(/\s+$/, "");
+}
+
+function gitResult(args, root) {
+  const result = spawnSync("git", args, { cwd: root, encoding: "utf8" });
+  return {
+    ok: !result.error && result.status === 0,
+    status: result.status,
+    stdout: String(result.stdout || "").replace(/\s+$/, ""),
+    stderr: String(result.stderr || "").replace(/\s+$/, ""),
+    error: result.error || null,
+  };
+}
+
+function statusLabel(status) {
+  return t(`status.${status}`);
+}
+
+function formatBootstrapStatus(status) {
+  return t(`bootstrap.status.${String(status || "").trim()}`) || status || t("locale.none");
+}
+
+function formatBootstrapMode(mode) {
+  return t(`bootstrap.mode.${String(mode || "").trim()}`) || mode || t("locale.none");
+}
+
+function formatBootstrapReason(reason) {
+  return t(`bootstrap.reason.${String(reason || "").trim()}`) || reason || t("locale.none");
+}
+
+function listOrNone(items) {
+  const values = (items || []).filter(Boolean);
+  return values.length ? values.join(", ") : t("locale.none");
+}
+
+/* ── repo snapshot ── */
+
 function getRepoSnapshot(contextOrRoot) {
   const context = config.ensureContext(contextOrRoot);
   const repoRoot = context.workspaceRoot;
-  const branch = git(["branch", "--show-current"], repoRoot) || "detached";
+  const insideWorkTree = gitResult(["rev-parse", "--is-inside-work-tree"], repoRoot);
+  if (!insideWorkTree.ok || insideWorkTree.stdout.trim() !== "true") {
+    return {
+      generatedAt: nowIso(),
+      available: false,
+      state: "not_initialized",
+      branch: null,
+      clean: null,
+      staged: 0,
+      unstaged: 0,
+      untracked: 0,
+      ahead: 0,
+      behind: 0,
+      hasUpstream: false,
+      lastCommit: null,
+    };
+  }
+
+  const branchResult = gitResult(["branch", "--show-current"], repoRoot);
+  const branch = branchResult.ok ? branchResult.stdout.trim() : "";
   const status = git(["status", "--short"], repoRoot) || "";
   const lines = status.split(/\r?\n/).filter(Boolean);
   const lastCommitRaw = git(["log", "-1", "--pretty=format:%H%n%cs%n%s"], repoRoot);
-  const divergenceRaw = git(["rev-list", "--left-right", "--count", "@{upstream}...HEAD"], repoRoot);
-
-  let staged = 0;
-  let unstaged = 0;
+  const upstream = gitResult(["rev-parse", "--abbrev-ref", "@{upstream}"], repoRoot);
+  const divergenceRaw = upstream.ok
+    ? git(["rev-list", "--left-right", "--count", "@{upstream}...HEAD"], repoRoot)
+    : null;
+
+  let staged = 0;
+  let unstaged = 0;
   let untracked = 0;
 
   lines.forEach((line) => {
@@ -78,27 +129,40 @@ function getRepoSnapshot(contextOrRoot) {
 
   let ahead = 0;
   let behind = 0;
-  if (divergenceRaw) {
-    const [left, right] = divergenceRaw.split(/\s+/).map(Number);
-    behind = Number.isFinite(left) ? left : 0;
-    ahead = Number.isFinite(right) ? right : 0;
-  }
-
-  return { generatedAt: nowIso(), branch, clean: lines.length === 0, staged, unstaged, untracked, ahead, behind, lastCommit };
-}
-
-function refreshRepoRuntime(root, options = {}) {
-  const context = config.ensureContext(root);
-  const runtimeFile = config.runtimeFilePath(context);
-  fs.mkdirSync(path.dirname(runtimeFile), { recursive: true });
-  const snapshot = getRepoSnapshot(context);
-  writeJson(runtimeFile, snapshot);
-  if (!options.quiet) {
-    console.log(t("cli.runtimeUpdated", { path: path.relative(context.workspaceRoot, runtimeFile) }));
+  if (divergenceRaw) {
+    const [left, right] = divergenceRaw.split(/\s+/).map(Number);
+    behind = Number.isFinite(left) ? left : 0;
+    ahead = Number.isFinite(right) ? right : 0;
   }
-  return snapshot;
+
+  return {
+    generatedAt: nowIso(),
+    available: true,
+    state: branch ? "ready" : "detached",
+    branch: branch || null,
+    clean: lines.length === 0,
+    staged,
+    unstaged,
+    untracked,
+    ahead,
+    behind,
+    hasUpstream: upstream.ok,
+    lastCommit,
+  };
 }
 
+function refreshRepoRuntime(root, options = {}) {
+  const context = config.ensureContext(root);
+  const runtimeFile = config.runtimeFilePath(context);
+  fs.mkdirSync(path.dirname(runtimeFile), { recursive: true });
+  const snapshot = getRepoSnapshot(context);
+  writeJson(runtimeFile, snapshot);
+  if (!options.quiet) {
+    console.log(t("cli.runtimeUpdated", { path: path.relative(context.workspaceRoot, runtimeFile) }));
+  }
+  return snapshot;
+}
+
 /* ── derive ── */
 
 function getPhaseInfo(phaseId, phases) {
@@ -115,16 +179,42 @@ function compareTasks(a, b, phases) {
   return a.title.localeCompare(b.title, getLocale());
 }
 
-function derive(control) {
-  const phases = config.getPhases(control);
-  const tasks = [...control.tasks].sort((a, b) => compareTasks(a, b, phases));
-  const completedIds = new Set(tasks.filter((t) => t.status === "completed").map((t) => t.id));
-  const closedStatuses = new Set(["completed", "cancelled"]);
+function detectCircularDeps(tasks) {
+  const visited = new Set();
+  const inStack = new Set();
+  const cycles = [];
+  function dfs(id) {
+    if (inStack.has(id)) { cycles.push(id); return; }
+    if (visited.has(id)) return;
+    visited.add(id);
+    inStack.add(id);
+    const task = tasks.find((t) => t.id === id);
+    if (task) (task.dependsOn || []).forEach((dep) => dfs(dep));
+    inStack.delete(id);
+  }
+  tasks.forEach((t) => dfs(t.id));
+  return cycles;
+}
+
+function derive(control) {
+  const phases = config.getPhases(control);
+  const tasks = [...control.tasks].sort((a, b) => compareTasks(a, b, phases));
+  const completedIds = new Set(tasks.filter((t) => t.status === "completed").map((t) => t.id));
+  const allIds = new Set(tasks.map((t) => t.id));
+  const closedStatuses = new Set(["completed", "cancelled"]);
+  const phantomDeps = [];
 
   const readyTasks = tasks
     .filter((task) => {
       if (task.status !== "pending") return false;
-      return (task.dependsOn || []).every((dep) => completedIds.has(dep));
+      const validDeps = (task.dependsOn || []).filter((dep) => {
+        if (!allIds.has(dep)) {
+          phantomDeps.push({ taskId: task.id, missingDep: dep });
+          return false;
+        }
+        return true;
+      });
+      return validDeps.every((dep) => completedIds.has(dep));
     })
     .sort((a, b) => {
       const focusPhase = control.meta.focusPhase || "";
@@ -139,22 +229,27 @@ function derive(control) {
   const reviewTasks = tasks.filter((t) => t.status === "in_review");
   const openTasks = tasks.filter((t) => !["completed", "cancelled"].includes(t.status));
   const requiredOpenTasks = tasks.filter((t) => t.required !== false && !["completed", "cancelled"].includes(t.status));
+  const projectCompleted = requiredOpenTasks.length === 0 && tasks.length > 0;
 
   const activePhase =
     phases.find((p) => requiredOpenTasks.some((t) => t.phase === p.id)) ||
-    phases[phases.length - 1];
+    (projectCompleted ? phases[phases.length - 1] : phases[0]);
 
-  const phaseStats = phases.map((phase) => {
-    const phaseTasks = tasks.filter((t) => t.phase === phase.id && t.required !== false);
-    const completed = phaseTasks.filter((t) => t.status === "completed").length;
-    const closed = phaseTasks.filter((t) => closedStatuses.has(t.status)).length;
-    return { ...phase, total: phaseTasks.length, completed, closed, remaining: phaseTasks.length - closed };
-  });
+  const phaseStats = phases.map((phase) => {
+    const phaseTasks = tasks.filter((t) => t.phase === phase.id && t.required !== false);
+    const completed = phaseTasks.filter((t) => t.status === "completed").length;
+    const closed = phaseTasks.filter((t) => closedStatuses.has(t.status)).length;
+    return { ...phase, total: phaseTasks.length, completed, closed, remaining: phaseTasks.length - closed };
+  });
 
   const nextTask = activeTasks[0] || readyTasks[0] || blockers[0] || openTasks[0] || null;
+  const circularDeps = detectCircularDeps(tasks);
 
   return {
     tasks, blockers, activeTasks, reviewTasks, readyTasks, nextTask, activePhase, phaseStats,
+    projectCompleted,
+    circularDeps,
+    phantomDeps,
     openFindings: (control.findings || []).filter((f) => f.status === "open"),
     resolvedFindings: (control.findings || []).filter((f) => f.status === "resolved"),
     totals: {
@@ -171,12 +266,13 @@ function derive(control) {
 
 /* ── render ── */
 
-function renderTask(task, phases) {
-  const phase = getPhaseInfo(task.phase, phases);
-  const detail = task.blocker || task.summary || "";
-  const detailSuffix = detail ? ` — ${detail}` : "";
-  return `- ${STATUS_ICONS[task.status]} \`${task.id}\` [${task.priority}] ${task.title} (${phase.id} · ${phase.label} · ${task.stream})${detailSuffix}`;
-}
+function renderTask(task, phases, options = {}) {
+  const phase = getPhaseInfo(task.phase, phases);
+  const detail = task.blocker || task.summary || "";
+  const detailSuffix = detail ? ` — ${detail}` : "";
+  const token = options.cli ? fmt.statusToken(task.status) : STATUS_ICONS[task.status];
+  return `- ${token} \`${task.id}\` [${task.priority}] ${task.title} (${phase.id} · ${phase.label} · ${task.stream})${detailSuffix}`;
+}
 
 function renderTaskPlan(control) {
   const phases = config.getPhases(control);
@@ -284,7 +380,7 @@ function renderProgress(control) {
     `## ${t("doc.section.currentState")}`,
     `- ${t("doc.label.phase")}: ${state.activePhase.label} (${state.activePhase.index}/${phases.length})`,
     `- ${t("doc.label.blockers")}: ${blockersLabel}`,
-    `- ${t("doc.label.lastTest")}: ${CHECK_ICONS[lastTest.status]} ${lastTest.date || t("status.pending")}${lastTest.note ? ` — ${lastTest.note}` : ""}`,
+    `- ${t("doc.label.lastTest")}: ${CHECK_ICONS[lastTest.status]} ${lastTest.date || t("status.pending")}${lastTest.note ? ` — ${lastTest.note}` : ""}`,
     `- ${t("doc.label.nextStepShort")}: ${nextStep}`,
     `- ${t("doc.label.lastUpdate")}: ${(control.meta.updatedAt || "").slice(0, 10)}`,
     "",
@@ -359,11 +455,11 @@ function buildDocMap(control) {
   return { taskPlan: renderTaskPlan(control), progress: renderProgress(control), findings: renderFindings(control) };
 }
 
-function getDocDrift(root, control) {
-  const context = config.ensureContext(root);
-  const docs = buildDocMap(control);
-  const docFiles = config.docFilePaths(context);
-  return Object.entries({ task_plan: [docFiles.taskPlan, docs.taskPlan], progress: [docFiles.progress, docs.progress], findings: [docFiles.findings, docs.findings] })
+function getDocDrift(root, control) {
+  const context = config.ensureContext(root);
+  const docs = buildDocMap(control);
+  const docFiles = config.docFilePaths(context);
+  return Object.entries({ task_plan: [docFiles.taskPlan, docs.taskPlan], progress: [docFiles.progress, docs.progress], findings: [docFiles.findings, docs.findings] })
     .filter(([, [filePath, expected]]) => {
       if (!fs.existsSync(filePath)) return true;
       return fs.readFileSync(filePath, "utf8").replace(/\r\n/g, "\n") !== `${expected}\n`;
@@ -371,21 +467,34 @@ function getDocDrift(root, control) {
     .map(([name]) => name);
 }
 
-function syncDocs(root, control) {
-  const context = config.ensureContext(root);
-  const docs = buildDocMap(control);
-  const docFiles = config.docFilePaths(context);
-  writeText(docFiles.taskPlan, `${docs.taskPlan}\n`);
-  writeText(docFiles.progress, `${docs.progress}\n`);
-  writeText(docFiles.findings, `${docs.findings}\n`);
-}
+function syncDocs(root, control, options = {}) {
+  const context = config.ensureContext(root);
+  const docs = buildDocMap(control);
+  const docFiles = config.docFilePaths(context);
+  const pairs = [
+    [docFiles.taskPlan, docs.taskPlan],
+    [docFiles.progress, docs.progress],
+    [docFiles.findings, docs.findings],
+  ];
+  for (const [filePath, content] of pairs) {
+    if (!options.force && fs.existsSync(filePath)) {
+      const existing = fs.readFileSync(filePath, "utf8");
+      const isAutoGenerated = existing.includes(t("doc.autogenerated"));
+      if (!isAutoGenerated && existing.trim()) {
+        console.log(t("control.docsOverwriteWarning", { file: path.basename(filePath) }));
+        continue;
+      }
+    }
+    writeText(filePath, `${content}\n`);
+  }
+}
 
 /* ── task management ── */
 
-function updateTask(root, control, action, taskId, note) {
-  const context = config.ensureContext(root);
-  const task = control.tasks.find((item) => item.id === taskId);
-  if (!task) throw new Error(t("cli.taskNotFound", { taskId }));
+function updateTask(root, control, action, taskId, note) {
+  const context = config.ensureContext(root);
+  const task = control.tasks.find((item) => item.id === taskId);
+  if (!task) throw new Error(t("cli.taskNotFound", { taskId }));
 
   const actionMap = { start: "in_progress", review: "in_review", complete: "completed", done: "completed", block: "blocked", pending: "pending", cancel: "cancelled" };
 
@@ -396,6 +505,10 @@ function updateTask(root, control, action, taskId, note) {
     const nextStatus = actionMap[action];
     if (!nextStatus) throw new Error(t("cli.actionNotSupported", { action }));
 
+    if (task.status === nextStatus) {
+      console.log(t("control.taskAlreadyStatus", { taskId, status: nextStatus }));
+      return;
+    }
     task.status = nextStatus;
     if (nextStatus === "blocked") {
       task.blocker = note || task.blocker || t("cli.undocumentedBlocker");
@@ -406,47 +519,50 @@ function updateTask(root, control, action, taskId, note) {
     task.history.push({ at: nowIso(), action, note: note || "" });
   }
 
-  config.saveControl(context, control);
-  syncDocs(context, control);
-  refreshRepoRuntime(context, { quiet: true });
-}
+  config.saveControl(context, control);
+  syncDocs(context, control);
+  refreshRepoRuntime(context, { quiet: true });
+}
 
 /* ── CLI commands ── */
 
-function initLocale(root) {
-  try {
-    const control = config.loadControl(config.ensureContext(root));
-    setLocale(config.getLocale(control));
-  } catch (_err) {
-    setLocale("es");
+function initLocale(root) {
+  try {
+    const control = config.loadControl(config.ensureContext(root));
+    setLocale(config.getLocale(control));
+  } catch (_err) {
+    setLocale("es");
   }
 }
 
-function cmdStatus(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const control = config.loadControl(context);
-  const state = derive(control);
-  const phases = config.getPhases(control);
-  const repo = refreshRepoRuntime(context, { quiet: true });
-  const drift = getDocDrift(context, control);
-  const envAudit = env.auditEnvironment(context, control);
-
+function cmdStatus(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const control = config.loadControl(context);
+  const state = derive(control);
+  const phases = config.getPhases(control);
+  const repo = refreshRepoRuntime(context, { quiet: true });
+  const drift = getDocDrift(context, control);
+  const envAudit = env.auditEnvironment(context, control);
+
   console.log(t("cli.status.title", { projectName: control.meta.projectName }));
   console.log(t("cli.status.focus", { focus: control.meta.currentFocus }));
   console.log(t("cli.status.activePhase", { phaseId: state.activePhase.id, phaseLabel: state.activePhase.label }));
-  console.log(`Layout: ${context.layout} | Workspace: ${context.workspaceRoot}`);
+  console.log(t("cli.status.layout", { layout: context.layout, workspace: context.workspaceRoot }));
   if (context.layout === "split") {
-    console.log(`App: ${context.appRoot}`);
-    console.log(`Ops: ${context.opsRoot}`);
+    console.log(t("cli.status.appRoot", { path: context.appRoot }));
+    console.log(t("cli.status.opsRoot", { path: context.opsRoot }));
   }
   if (control.meta?.opera?.bootstrap?.status) {
-    console.log(t("cli.status.bootstrap", { status: control.meta.opera.bootstrap.status, locale: config.getLocale(control) }));
+    console.log(t("cli.status.bootstrap", {
+      status: formatBootstrapStatus(control.meta.opera.bootstrap.status),
+      locale: config.getLocale(control),
+    }));
     if (control.meta.opera.bootstrap.mode) {
-      console.log(`Bootstrap mode: ${control.meta.opera.bootstrap.mode}`);
+      console.log(t("cli.status.bootstrapMode", { value: formatBootstrapMode(control.meta.opera.bootstrap.mode) }));
     }
     if (control.meta.opera.bootstrap.routeReason) {
-      console.log(`Bootstrap route: ${control.meta.opera.bootstrap.routeReason}`);
+      console.log(t("cli.status.bootstrapReason", { value: formatBootstrapReason(control.meta.opera.bootstrap.routeReason) }));
     }
   }
   console.log(t("cli.status.tasks", {
@@ -454,41 +570,49 @@ function cmdStatus(root) {
     inReview: state.totals.inReview, pending: state.totals.pending, blocked: state.totals.blocked,
   }));
   console.log("");
-  console.log(t("cli.status.readyTasks"));
-  if (state.readyTasks.length) {
-    state.readyTasks.slice(0, 5).forEach((task) => console.log(renderTask(task, phases)));
-  } else {
-    console.log(t("cli.status.noReadyTasks"));
-  }
+  console.log(t("cli.status.readyTasks"));
+  if (state.readyTasks.length) {
+    state.readyTasks.slice(0, 5).forEach((task) => console.log(renderTask(task, phases, { cli: true })));
+  } else {
+    console.log(t("cli.status.noReadyTasks"));
+  }
   console.log("");
-  console.log(t("cli.status.blockers"));
-  if (state.blockers.length) {
-    state.blockers.forEach((task) => console.log(renderTask(task, phases)));
-  } else {
-    console.log(t("cli.status.noBlockers"));
-  }
+  console.log(t("cli.status.blockers"));
+  if (state.blockers.length) {
+    state.blockers.forEach((task) => console.log(renderTask(task, phases, { cli: true })));
+  } else {
+    console.log(t("cli.status.noBlockers"));
+  }
   console.log("");
   console.log(t("cli.status.decisions"));
   if ((control.decisionsPending || []).length) {
     control.decisionsPending.forEach((d) => console.log(`- ${d.title} (${d.owner}) — ${d.impact}`));
   } else {
     console.log(`- ${t("cli.status.noDecisions")}`);
-  }
-  console.log("");
-  console.log(t("cli.status.repo"));
-  const treeStatus = repo.clean
-    ? t("cli.status.treeClean")
-    : t("cli.status.treeDirty", { staged: repo.staged, unstaged: repo.unstaged, untracked: repo.untracked });
-  console.log(`- ${t("cli.status.branch", { branch: repo.branch, treeStatus })}`);
-  if (repo.lastCommit) {
-    console.log(`- ${t("cli.status.lastCommit", { hash: repo.lastCommit.shortHash, subject: repo.lastCommit.subject })}`);
-  }
-  if (repo.ahead || repo.behind) {
-    console.log(`- ${t("cli.status.divergence", { ahead: repo.ahead, behind: repo.behind })}`);
+  }
+  console.log("");
+  console.log(t("cli.status.repo"));
+  if (!repo.available) {
+    console.log(`- ${t("cli.status.gitState", { state: t("cli.status.gitNotInitialized") })}`);
+    console.log(`- ${t("cli.status.gitAction")}`);
+  } else {
+    const branchLabel = repo.state === "detached" ? t("cli.status.branchDetached") : repo.branch;
+    const treeStatus = repo.clean
+      ? t("cli.status.treeClean")
+      : t("cli.status.treeDirty", { staged: repo.staged, unstaged: repo.unstaged, untracked: repo.untracked });
+    console.log(`- ${t("cli.status.branch", { branch: branchLabel, treeStatus })}`);
+    if (repo.lastCommit) {
+      console.log(`- ${t("cli.status.lastCommit", { hash: repo.lastCommit.shortHash, subject: repo.lastCommit.subject })}`);
+    }
+    if (!repo.hasUpstream) {
+      console.log(`- ${t("cli.status.noUpstream")}`);
+    } else if (repo.ahead || repo.behind) {
+      console.log(`- ${t("cli.status.divergence", { ahead: repo.ahead, behind: repo.behind })}`);
+    }
   }
   console.log(`- ${t("cli.status.runtime", { path: path.relative(context.workspaceRoot, config.runtimeFilePath(context)) })}`);
-  console.log(`- Env present: ${envAudit.presentKeys.length ? envAudit.presentKeys.join(", ") : "none"}`);
-  console.log(`- Env missing: ${envAudit.missingKeys.length ? envAudit.missingKeys.join(", ") : "none"}`);
+  console.log(`- ${t("cli.status.envPresent", { value: listOrNone(envAudit.presentKeys) })}`);
+  console.log(`- ${t("cli.status.envMissing", { value: listOrNone(envAudit.missingKeys) })}`);
   console.log("");
   const syncStatus = drift.length
     ? t("cli.status.docsSyncedNo", { files: drift.join(", ") })
@@ -496,13 +620,26 @@ function cmdStatus(root) {
   console.log(t("cli.status.docsSynced", { status: syncStatus }));
 }
 
-function cmdNext(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const control = config.loadControl(context);
-  const ready = derive(control).readyTasks.slice(0, 10);
+function cmdNext(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const control = config.loadControl(context);
+  const state = derive(control);
+  if (state.circularDeps.length) {
+    console.log(t("control.circularDependency", { taskIds: state.circularDeps.join(", ") }));
+  }
+  const ready = state.readyTasks.slice(0, 10);
   if (!ready.length) {
-    console.log(t("cli.noReadyTasks"));
+    if (state.projectCompleted) {
+      console.log(t("cli.noReadyTasks.allDone"));
+    } else if (state.blockers.length) {
+      console.log(t("cli.noReadyTasks.blocked", { count: state.blockers.length }));
+      for (const task of state.blockers.slice(0, 5)) {
+        console.log(`  - ${task.id}: ${task.blocker || task.title}`);
+      }
+    } else {
+      console.log(t("cli.noReadyTasks"));
+    }
     return;
   }
   ready.forEach((task, i) => {
@@ -513,114 +650,139 @@ function cmdNext(root) {
   });
 }
 
-function cmdSync(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const control = config.loadControl(context);
-  env.syncEnvironment(context, control);
-  syncDocs(context, control);
-  refreshRepoRuntime(context, { quiet: true });
-  console.log(t("cli.docsSynced"));
-}
-
-function cmdRefreshRepo(root, args) {
-  refreshRepoRuntime(config.ensureContext(root), { quiet: (args || []).includes("--quiet") });
-}
-
-function cmdTask(root, args) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const [action, taskId, ...noteParts] = args || [];
-  if (!action || !taskId) throw new Error(t("cli.mustProvideActionAndId"));
-  const control = config.loadControl(context);
-  updateTask(context, control, action, taskId, noteParts.join(" ").trim());
-  console.log(t("cli.taskUpdated", { taskId, action }));
-}
-
-function cmdInstallHooks(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const hooksPath = context.layout === "split" ? "ops/.githooks" : ".githooks";
-  const result = spawnSync("git", ["config", "core.hooksPath", hooksPath], { cwd: context.workspaceRoot, encoding: "utf8" });
-  if (result.error || result.status !== 0) throw new Error(t("cli.hooksError"));
-  console.log(t("cli.hooksInstalled"));
-}
-
-function cmdHelp() {
-  console.log(`trackops — ${t("cli.help.title")}`);
-  console.log("");
-  console.log(`${t("cli.help.usage")} trackops <command> [args]`);
-  console.log("");
-  console.log(t("cli.help.commands"));
-  console.log("  init [--with-opera] [--legacy-layout] [--locale es|en] [--name \"...\"] [--no-bootstrap]");
-  console.log("       [--bootstrap-mode auto|direct|handoff] [--technical-level low|medium|high|senior]");
-  console.log("       [--project-state idea|draft|existing_repo|advanced] [--docs-state none|notes|sos|spec_dossier|repo_docs]");
-  console.log("       [--decision-ownership user|shared|agent]");
-  console.log(`    ${t("cli.help.init.desc")}`);
-  console.log("  workspace status|migrate");
-  console.log(`    ${t("cli.help.workspace.desc")}`);
-  console.log("  env status|sync");
-  console.log(`    ${t("cli.help.env.desc")}`);
-  console.log("  release [--push]");
-  console.log(`    ${t("cli.help.release.desc")}`);
-  console.log("  version");
-  console.log(`    ${t("cli.help.version.desc")}`);
-  console.log("  status");
-  console.log(`    ${t("cli.help.status.desc")}`);
-  console.log("  next");
-  console.log(`    ${t("cli.help.next.desc")}`);
-  console.log("  sync");
-  console.log(`    ${t("cli.help.sync.desc")}`);
-  console.log("  dashboard [--port N] [--host HOST] [--public] [--strict-port]");
-  console.log(`    ${t("cli.help.dashboard.desc")}`);
-  console.log("  refresh-repo [--quiet]");
-  console.log(`    ${t("cli.help.refreshRepo.desc")}`);
-  console.log("  install-hooks");
-  console.log(`    ${t("cli.help.installHooks.desc")}`);
-  console.log("  register");
-  console.log(`    ${t("cli.help.register.desc")}`);
-  console.log("  projects");
-  console.log(`    ${t("cli.help.projects.desc")}`);
-  console.log("  task <action> <id> [note]");
-  console.log(`    ${t("cli.help.task.desc")}`);
-  console.log("  opera install|bootstrap|handoff|status|configure|upgrade");
-  console.log(`    ${t("cli.help.opera.desc")}`);
-  console.log(`    ${t("cli.help.opera.upgradeHint")}`);
-  console.log("  locale get|set [es|en]");
-  console.log(`    ${t("cli.help.locale.desc")}`);
-  console.log("  doctor locale");
-  console.log(`    ${t("cli.help.doctor.desc")}`);
-  console.log("  skill install|list|remove|catalog <name>");
-  console.log(`    ${t("cli.help.skill.desc")}`);
-  console.log("  help");
+function cmdSync(root, args) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const control = config.loadControl(context);
+  if ((args || []).includes("--dry-run")) {
+    const drift = getDocDrift(context, control);
+    if (drift.length) {
+      console.log(t("cli.sync.dryRunWouldUpdate", { files: drift.join(", ") }));
+    } else {
+      console.log(t("cli.sync.dryRunInSync"));
+    }
+    return;
+  }
+  const state = derive(control);
+  if (state.activePhase && control.meta.focusPhase !== state.activePhase.id) {
+    control.meta.focusPhase = state.activePhase.id;
+    config.saveControl(context, control);
+  }
+  env.syncEnvironment(context, control);
+  if (config.isOperaInstalled(control)) {
+    const bootstrap = require("./opera-bootstrap");
+    const result = bootstrap.revalidateContract(context, control);
+    if (result.changed) {
+      console.log(t("control.contractStale"));
+    }
+  }
+  const force = (args || []).includes("--force");
+  syncDocs(context, control, { force });
+  refreshRepoRuntime(context, { quiet: true });
+  console.log(t("cli.docsSynced"));
+}
+
+function cmdRefreshRepo(root, args) {
+  refreshRepoRuntime(config.ensureContext(root), { quiet: (args || []).includes("--quiet") });
+}
+
+function cmdTask(root, args) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const [action, taskId, ...noteParts] = args || [];
+  if (!action || !taskId) throw new Error(t("cli.mustProvideActionAndId"));
+  const control = config.loadControl(context);
+  updateTask(context, control, action, taskId, noteParts.join(" ").trim());
+  console.log(t("cli.taskUpdated", { taskId, action }));
+}
+
+function cmdInstallHooks(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const hooksPath = context.layout === "split" ? "ops/.githooks" : ".githooks";
+  const result = spawnSync("git", ["config", "core.hooksPath", hooksPath], { cwd: context.workspaceRoot, encoding: "utf8" });
+  if (result.error || result.status !== 0) throw new Error(t("cli.hooksError"));
+  console.log(t("cli.hooksInstalled"));
+}
+
+function cmdHelp() {
+  console.log(`trackops — ${t("cli.help.title")}`);
+  console.log("");
+  console.log(`${t("cli.help.usage")} trackops <command> [args]`);
+  console.log("");
+  console.log(t("cli.help.commands"));
+  console.log("  init [--with-opera] [--legacy-layout] [--locale es|en] [--name \"...\"] [--no-bootstrap]");
+  console.log("       [--bootstrap-mode auto|direct|handoff] [--technical-level low|medium|high|senior]");
+  console.log("       [--project-state idea|draft|existing_repo|advanced] [--docs-state none|notes|sos|spec_dossier|repo_docs]");
+  console.log("       [--decision-ownership user|shared|agent]");
+  console.log(`    ${t("cli.help.init.desc")}`);
+  console.log("  workspace status|migrate");
+  console.log(`    ${t("cli.help.workspace.desc")}`);
+  console.log("  env status|sync");
+  console.log(`    ${t("cli.help.env.desc")}`);
+  console.log("  release [--push]");
+  console.log(`    ${t("cli.help.release.desc")}`);
+  console.log("  version");
+  console.log(`    ${t("cli.help.version.desc")}`);
+  console.log("  status");
+  console.log(`    ${t("cli.help.status.desc")}`);
+  console.log("  next");
+  console.log(`    ${t("cli.help.next.desc")}`);
+  console.log("  sync");
+  console.log(`    ${t("cli.help.sync.desc")}`);
+  console.log("  dashboard [--port N] [--host HOST] [--public] [--strict-port]");
+  console.log(`    ${t("cli.help.dashboard.desc")}`);
+  console.log("  refresh-repo [--quiet]");
+  console.log(`    ${t("cli.help.refreshRepo.desc")}`);
+  console.log("  install-hooks");
+  console.log(`    ${t("cli.help.installHooks.desc")}`);
+  console.log("  register");
+  console.log(`    ${t("cli.help.register.desc")}`);
+  console.log("  projects");
+  console.log(`    ${t("cli.help.projects.desc")}`);
+  console.log("  task <action> <id> [note]");
+  console.log(`    ${t("cli.help.task.desc")}`);
+  console.log("  opera install|bootstrap|handoff|status|configure|upgrade");
+  console.log(`    ${t("cli.help.opera.desc")}`);
+  console.log(`    ${t("cli.help.opera.upgradeHint")}`);
+  console.log("  locale get|set [es|en]");
+  console.log(`    ${t("cli.help.locale.desc")}`);
+  console.log("  doctor locale");
+  console.log(`    ${t("cli.help.doctor.desc")}`);
+  console.log("  skill install|list|remove|catalog <name>");
+  console.log(`    ${t("cli.help.skill.desc")}`);
+  console.log("  help");
   console.log(`    ${t("cli.help.help.desc")}`);
   console.log("");
+  console.log(t("cli.help.globalFlags"));
+  console.log(`  ${t("cli.help.globalFlags.line1")}`);
+  console.log("");
   console.log(t("cli.help.globalWorkflow"));
   console.log(`  ${t("cli.help.globalWorkflow.line1")}`);
   console.log(`  ${t("cli.help.globalWorkflow.line2")}`);
-}
+}
 
 /* ── project-scoped API (used by server) ── */
 
-function forProject(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  return {
-    loadControl: () => config.loadControl(context),
-    saveControl: (ctrl) => config.saveControl(context, ctrl),
-    derive,
-    buildDocMap,
-    getDocDrift: (ctrl) => getDocDrift(context, ctrl),
-    syncDocs: (ctrl) => syncDocs(context, ctrl),
-    updateTask: (ctrl, action, id, note) => updateTask(context, ctrl, action, id, note),
-    getRepoSnapshot: () => getRepoSnapshot(context),
-    refreshRepoRuntime: (opts) => refreshRepoRuntime(context, opts),
-    getPhases: (ctrl) => config.getPhases(ctrl),
-    getLocale: (ctrl) => config.getLocale(ctrl),
-    statusLabel,
-    context,
-  };
-}
+function forProject(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  return {
+    loadControl: () => config.loadControl(context),
+    saveControl: (ctrl) => config.saveControl(context, ctrl),
+    derive,
+    buildDocMap,
+    getDocDrift: (ctrl) => getDocDrift(context, ctrl),
+    syncDocs: (ctrl) => syncDocs(context, ctrl),
+    updateTask: (ctrl, action, id, note) => updateTask(context, ctrl, action, id, note),
+    getRepoSnapshot: () => getRepoSnapshot(context),
+    refreshRepoRuntime: (opts) => refreshRepoRuntime(context, opts),
+    getPhases: (ctrl) => config.getPhases(ctrl),
+    getLocale: (ctrl) => config.getLocale(ctrl),
+    statusLabel,
+    context,
+  };
+}
 
 module.exports = {
   buildDocMap, derive, getDocDrift, getRepoSnapshot, refreshRepoRuntime, syncDocs, updateTask,