trackops 2.0.5 → 2.1.0

package/lib/control.js

@@ -4,26 +4,28 @@ 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 = {
-  pass: "\u2705",
-  warn: "\u26A0\uFE0F",
-  fail: "\u274C",
-  pending: "\u23F3",
-};
+const config = require("./config");
+const env = require("./env");
+const { t, setLocale, getLocale } = require("./i18n");
+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",
+  pending: "\u23F3",
+};
+const AUTO_GENERATED_MARKER = "<!-- trackops:auto-generated -->";
 
 /* ── helpers ── */
 
@@ -39,29 +41,273 @@ 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 getRepoSnapshot(contextOrRoot) {
-  const context = config.ensureContext(contextOrRoot);
-  const repoRoot = context.workspaceRoot;
-  const branch = git(["branch", "--show-current"], repoRoot) || "detached";
-  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;
+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");
+}
+
+function ensureAgentInbox(control) {
+  control.meta = control.meta || {};
+  control.meta.agentInbox = config.normalizeAgentInbox(control.meta.agentInbox);
+  return control.meta.agentInbox;
+}
+
+function makeInboxId(taskId, kind) {
+  return `ai-${String(taskId || "general").trim() || "general"}-${String(kind || "info").trim() || "info"}`;
+}
+
+function upsertAgentInstruction(control, payload = {}) {
+  const inbox = ensureAgentInbox(control);
+  const now = nowIso();
+  const instruction = config.normalizeAgentInbox({
+    pending: [{
+      id: payload.id || makeInboxId(payload.taskId, payload.kind),
+      taskId: payload.taskId || null,
+      kind: payload.kind || "verify_status",
+      message: payload.message || "",
+      status: "pending",
+      createdAt: payload.createdAt || now,
+      updatedAt: now,
+      createdBy: payload.createdBy || "system",
+      source: payload.source || null,
+      expectedStatus: payload.expectedStatus || null,
+      sessionId: payload.sessionId || null,
+    }],
+  }).pending[0];
+
+  const existingIndex = inbox.pending.findIndex((item) => item.id === instruction.id);
+  if (existingIndex >= 0) {
+    const existing = inbox.pending[existingIndex];
+    inbox.pending[existingIndex] = {
+      ...existing,
+      ...instruction,
+      createdAt: existing.createdAt || instruction.createdAt,
+    };
+  } else {
+    inbox.pending.unshift(instruction);
+  }
+  inbox.lastIssuedAt = now;
+  return instruction;
+}
+
+function resolveAgentInstructions(control, taskId, options = {}) {
+  const inbox = ensureAgentInbox(control);
+  const now = nowIso();
+  const kinds = Array.isArray(options.kinds) && options.kinds.length
+    ? new Set(options.kinds.map((kind) => String(kind || "").trim()))
+    : null;
+  const resolved = [];
+  const pending = [];
+
+  inbox.pending.forEach((item) => {
+    const matchesTask = !taskId || item.taskId === taskId;
+    const matchesKind = !kinds || kinds.has(item.kind);
+    if (matchesTask && matchesKind) {
+      const nextItem = {
+        ...item,
+        status: "resolved",
+        resolvedAt: now,
+        resolutionNote: String(options.note || "").trim() || null,
+        updatedAt: now,
+      };
+      inbox.history.unshift(nextItem);
+      resolved.push(nextItem);
+    } else {
+      pending.push(item);
+    }
+  });
+
+  inbox.pending = pending;
+  return resolved;
+}
+
+function ensureTaskExecution(task) {
+  task.execution = config.normalizeTaskExecution(task.execution);
+  return task.execution;
+}
+
+function setTaskExecutionContext(task, options = {}) {
+  const execution = ensureTaskExecution(task);
+  if (options.owner) execution.owner = config.normalizeExecutionOwner(options.owner);
+  if (options.actor) execution.lastActor = String(options.actor || "").trim() || execution.lastActor;
+  if (options.source) execution.lastSource = String(options.source || "").trim() || execution.lastSource;
+  if (Object.prototype.hasOwnProperty.call(options, "sessionId")) {
+    execution.currentSessionId = options.sessionId ? String(options.sessionId).trim() : null;
+    if (execution.currentSessionId) execution.lastSessionId = execution.currentSessionId;
+  }
+  if (Object.prototype.hasOwnProperty.call(options, "sessionStatus")) {
+    execution.lastSessionStatus = options.sessionStatus ? String(options.sessionStatus).trim() : null;
+  }
+  if (Object.prototype.hasOwnProperty.call(options, "awaitingUserConfirmation")) {
+    execution.awaitingUserConfirmation = options.awaitingUserConfirmation === true;
+  }
+  if (Object.prototype.hasOwnProperty.call(options, "verificationPending")) {
+    execution.verificationPending = options.verificationPending === true;
+  }
+  execution.updatedAt = nowIso();
+  return execution;
+}
+
+function buildUserExecutionInstruction(task, status, source) {
+  const sourceLabel = String(source || t("locale.none")).replace(/_/g, " ");
+  return t("agentInbox.awaitUser.message", {
+    taskId: task.id,
+    title: task.title,
+    status: statusLabel(status),
+    source: sourceLabel,
+  });
+}
+
+function buildVerificationInstruction(task, status, source) {
+  const sourceLabel = String(source || t("locale.none")).replace(/_/g, " ");
+  return t("agentInbox.verify.message", {
+    taskId: task.id,
+    title: task.title,
+    status: statusLabel(status),
+    source: sourceLabel,
+  });
+}
+
+function applyTaskStateTransition(control, task, transition, options = {}) {
+  const nextStatus = String(transition.status || "").trim();
+  const action = String(transition.action || "").trim();
+  const note = String(transition.note || "").trim();
+  const actor = String(options.actor || "system").trim() || "system";
+  const source = String(options.source || "system").trim() || "system";
+  const execution = setTaskExecutionContext(task, {
+    owner: options.owner || task.execution?.owner,
+    actor,
+    source,
+    sessionId: Object.prototype.hasOwnProperty.call(options, "sessionId") ? options.sessionId : undefined,
+  });
+
+  if (nextStatus && task.status !== nextStatus) {
+    task.status = nextStatus;
+  }
+  if (nextStatus === "blocked") {
+    task.blocker = note || task.blocker || t("cli.undocumentedBlocker");
+  } else if (nextStatus && nextStatus !== "blocked") {
+    delete task.blocker;
+  }
+
+  if (execution.owner === "user" && nextStatus === "in_progress") {
+    execution.awaitingUserConfirmation = true;
+    upsertAgentInstruction(control, {
+      taskId: task.id,
+      kind: "await_user_report",
+      message: buildUserExecutionInstruction(task, nextStatus, source),
+      createdBy: actor,
+      source,
+      expectedStatus: nextStatus,
+      sessionId: options.sessionId || null,
+    });
+  }
+
+  if (actor === "user" && nextStatus) {
+    execution.verificationPending = true;
+    upsertAgentInstruction(control, {
+      taskId: task.id,
+      kind: "verify_status",
+      message: buildVerificationInstruction(task, nextStatus, source),
+      createdBy: actor,
+      source,
+      expectedStatus: nextStatus,
+      sessionId: options.sessionId || null,
+    });
+  }
+
+  if (actor === "agent" || actor === "system") {
+    execution.verificationPending = false;
+    resolveAgentInstructions(control, task.id, {
+      kinds: ["verify_status"],
+      note: note || t("agentInbox.verify.resolved"),
+    });
+  }
+
+  if (nextStatus === "completed" || nextStatus === "blocked" || nextStatus === "cancelled") {
+    execution.awaitingUserConfirmation = false;
+    resolveAgentInstructions(control, task.id, {
+      kinds: ["await_user_report"],
+      note: note || t("agentInbox.awaitUser.resolved"),
+    });
+  }
+
+  if (action) {
+    task.history = task.history || [];
+    task.history.push({ at: nowIso(), action, note: note || "" });
+  }
+
+  return task;
+}
+
+/* ── repo snapshot ── */
+
+function getRepoSnapshot(contextOrRoot) {
+  const context = config.ensureContext(contextOrRoot);
+  const repoRoot = context.workspaceRoot;
+  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 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,14 +324,27 @@ 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 };
-}
+  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(),
+    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);
@@ -101,86 +360,299 @@ function refreshRepoRuntime(root, options = {}) {
 
 /* ── derive ── */
 
-function getPhaseInfo(phaseId, phases) {
-  return phases.find((p) => p.id === phaseId) || { id: phaseId, label: phaseId, index: 99 };
-}
-
-function compareTasks(a, b, phases) {
-  const phaseDelta = getPhaseInfo(a.phase, phases).index - getPhaseInfo(b.phase, phases).index;
-  if (phaseDelta !== 0) return phaseDelta;
-  const priorityDelta = PRIORITY_ORDER.indexOf(a.priority) - PRIORITY_ORDER.indexOf(b.priority);
-  if (priorityDelta !== 0) return priorityDelta;
-  const statusDelta = STATUS_ORDER.indexOf(a.status) - STATUS_ORDER.indexOf(b.status);
-  if (statusDelta !== 0) return statusDelta;
-  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"]);
-
-  const readyTasks = tasks
-    .filter((task) => {
-      if (task.status !== "pending") return false;
-      return (task.dependsOn || []).every((dep) => completedIds.has(dep));
-    })
-    .sort((a, b) => {
-      const focusPhase = control.meta.focusPhase || "";
-      const aFocused = a.phase === focusPhase ? 0 : 1;
-      const bFocused = b.phase === focusPhase ? 0 : 1;
-      if (aFocused !== bFocused) return aFocused - bFocused;
-      return compareTasks(a, b, phases);
-    });
-
-  const blockers = tasks.filter((t) => t.status === "blocked");
-  const activeTasks = tasks.filter((t) => t.status === "in_progress");
-  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 activePhase =
-    phases.find((p) => requiredOpenTasks.some((t) => t.phase === p.id)) ||
-    phases[phases.length - 1];
-
-  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;
-
-  return {
-    tasks, blockers, activeTasks, reviewTasks, readyTasks, nextTask, activePhase, phaseStats,
-    openFindings: (control.findings || []).filter((f) => f.status === "open"),
-    resolvedFindings: (control.findings || []).filter((f) => f.status === "resolved"),
-    totals: {
-      all: tasks.length,
-      completed: tasks.filter((t) => t.status === "completed").length,
-      pending: tasks.filter((t) => t.status === "pending").length,
-      inProgress: activeTasks.length,
-      inReview: reviewTasks.length,
-      blocked: blockers.length,
-      cancelled: tasks.filter((t) => t.status === "cancelled").length,
-    },
-  };
-}
-
-/* ── 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 renderTaskPlan(control) {
-  const phases = config.getPhases(control);
-  const state = derive(control);
+function getPhaseInfo(phaseId, phases) {
+  return phases.find((p) => p.id === phaseId) || { id: phaseId, label: phaseId, index: 99 };
+}
+
+function compareTasks(a, b, phases) {
+  const aSequence = Number.isFinite(Number(a.sequence)) ? Number(a.sequence) : Number.POSITIVE_INFINITY;
+  const bSequence = Number.isFinite(Number(b.sequence)) ? Number(b.sequence) : Number.POSITIVE_INFINITY;
+  if (aSequence !== bSequence) return aSequence - bSequence;
+  const phaseDelta = getPhaseInfo(a.phase, phases).index - getPhaseInfo(b.phase, phases).index;
+  if (phaseDelta !== 0) return phaseDelta;
+  const priorityDelta = PRIORITY_ORDER.indexOf(a.priority) - PRIORITY_ORDER.indexOf(b.priority);
+  if (priorityDelta !== 0) return priorityDelta;
+  const statusDelta = STATUS_ORDER.indexOf(a.status) - STATUS_ORDER.indexOf(b.status);
+  if (statusDelta !== 0) return statusDelta;
+  const titleDelta = a.title.localeCompare(b.title, getLocale());
+  if (titleDelta !== 0) return titleDelta;
+  return a.id.localeCompare(b.id, getLocale());
+}
+
+function detectCircularDeps(tasks) {
+  const taskMap = new Map(tasks.map((task) => [task.id, task]));
+  const visited = new Set();
+  const inStack = new Set();
+  const cycles = new Set();
+  function dfs(id) {
+    if (inStack.has(id)) { cycles.add(id); return; }
+    if (visited.has(id)) return;
+    visited.add(id);
+    inStack.add(id);
+    const task = taskMap.get(id);
+    if (task) (task.dependsOn || []).forEach((dep) => dfs(dep));
+    inStack.delete(id);
+  }
+  tasks.forEach((t) => dfs(t.id));
+  return [...cycles];
+}
+
+function detectHierarchyIssues(tasks) {
+  const taskMap = new Map(tasks.map((task) => [task.id, task]));
+  const hierarchyCycles = new Set();
+  const phantomParents = [];
+  const visiting = new Set();
+  const visited = new Set();
+
+  function visit(task) {
+    if (!task || visited.has(task.id)) return;
+    if (visiting.has(task.id)) {
+      hierarchyCycles.add(task.id);
+      return;
+    }
+    visiting.add(task.id);
+    if (task.parentId) {
+      if (task.parentId === task.id) {
+        hierarchyCycles.add(task.id);
+      } else if (!taskMap.has(task.parentId)) {
+        phantomParents.push({ taskId: task.id, missingParentId: task.parentId });
+      } else {
+        visit(taskMap.get(task.parentId));
+        if (hierarchyCycles.has(task.parentId)) hierarchyCycles.add(task.id);
+      }
+    }
+    visiting.delete(task.id);
+    visited.add(task.id);
+  }
+
+  tasks.forEach((task) => visit(task));
+  return { hierarchyCycles: [...hierarchyCycles], phantomParents };
+}
+
+function derive(control) {
+  const phases = config.getPhases(control);
+  const baseTasks = (control.tasks || []).map((task) => config.normalizeTaskShape(task));
+  const taskMap = new Map(baseTasks.map((task) => [task.id, { ...task, rawStatus: task.status }]));
+  const { hierarchyCycles, phantomParents } = detectHierarchyIssues(baseTasks);
+  const cycleSet = new Set(hierarchyCycles);
+  const childrenByParent = new Map();
+
+  taskMap.forEach((task) => {
+    const declaredParentId = task.parentId;
+    task.declaredParentId = declaredParentId;
+    if (!declaredParentId || declaredParentId === task.id || cycleSet.has(task.id) || !taskMap.has(declaredParentId)) {
+      task.parentId = null;
+      return;
+    }
+    if (!childrenByParent.has(declaredParentId)) childrenByParent.set(declaredParentId, []);
+    childrenByParent.get(declaredParentId).push(task);
+  });
+
+  childrenByParent.forEach((children) => children.sort((a, b) => compareTasks(a, b, phases)));
+
+  const leafCache = new Map();
+  const statusCache = new Map();
+  const visitedTree = new Set();
+  const closedStatuses = new Set(["completed", "cancelled"]);
+
+  function getLeafDescendants(taskId) {
+    if (leafCache.has(taskId)) return leafCache.get(taskId);
+    const children = childrenByParent.get(taskId) || [];
+    if (!children.length) {
+      const leaves = [taskMap.get(taskId)].filter(Boolean);
+      leafCache.set(taskId, leaves);
+      return leaves;
+    }
+    const leaves = children.flatMap((child) => getLeafDescendants(child.id));
+    leafCache.set(taskId, leaves);
+    return leaves;
+  }
+
+  function computeStatus(taskId) {
+    if (statusCache.has(taskId)) return statusCache.get(taskId);
+    const task = taskMap.get(taskId);
+    if (!task) return "pending";
+    const children = childrenByParent.get(taskId) || [];
+    if (!children.length) {
+      statusCache.set(taskId, task.rawStatus);
+      return task.rawStatus;
+    }
+    const requiredLeaves = getLeafDescendants(taskId).filter((leaf) => leaf.required !== false);
+    let nextStatus = "pending";
+    if (requiredLeaves.some((leaf) => leaf.rawStatus === "blocked")) nextStatus = "blocked";
+    else if (requiredLeaves.some((leaf) => leaf.rawStatus === "in_review")) nextStatus = "in_review";
+    else if (requiredLeaves.some((leaf) => leaf.rawStatus === "in_progress")) nextStatus = "in_progress";
+    else if (requiredLeaves.length && requiredLeaves.every((leaf) => closedStatuses.has(leaf.rawStatus)) && requiredLeaves.some((leaf) => leaf.rawStatus === "completed")) nextStatus = "completed";
+    statusCache.set(taskId, nextStatus);
+    return nextStatus;
+  }
+
+  const roots = [...taskMap.values()]
+    .filter((task) => !task.parentId)
+    .sort((a, b) => compareTasks(a, b, phases));
+  const treeTasks = [];
+
+  function flatten(task, depth = 0, rootId = task.id, rootTitle = task.title) {
+    if (!task || visitedTree.has(task.id)) return;
+    visitedTree.add(task.id);
+    const children = childrenByParent.get(task.id) || [];
+    const effectiveStatus = computeStatus(task.id);
+    const execution = config.normalizeTaskExecution(task.execution);
+    const derivedTask = {
+      ...task,
+      status: effectiveStatus,
+      effectiveStatus,
+      isParent: children.length > 0,
+      isLeaf: children.length === 0,
+      childrenIds: children.map((child) => child.id),
+      childrenCount: children.length,
+      depth,
+      rootId,
+      rootTitle,
+      sourceId: task.origin?.sourceId || null,
+      detached: task.origin?.detached === true,
+      execution,
+      executionOwner: execution.owner,
+      awaitingUserConfirmation: execution.awaitingUserConfirmation === true,
+      verificationPending: execution.verificationPending === true,
+      currentSessionId: execution.currentSessionId || null,
+    };
+    treeTasks.push(derivedTask);
+    children.forEach((child) => flatten(child, depth + 1, rootId, rootTitle));
+  }
+
+  roots.forEach((task) => flatten(task));
+  [...taskMap.values()].filter((task) => !visitedTree.has(task.id)).sort((a, b) => compareTasks(a, b, phases)).forEach((task) => flatten(task));
+
+  const allIds = new Set(treeTasks.map((task) => task.id));
+  const completedIds = new Set(treeTasks.filter((task) => task.status === "completed").map((task) => task.id));
+  const phantomDeps = [];
+  const actionableTasks = treeTasks.filter((task) => task.isLeaf);
+  const focusPhase = control.meta.focusPhase || "";
+
+  const readyTasks = actionableTasks
+    .filter((task) => {
+      if (task.status !== "pending") return false;
+      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 aFocused = a.phase === focusPhase ? 0 : 1;
+      const bFocused = b.phase === focusPhase ? 0 : 1;
+      if (aFocused !== bFocused) return aFocused - bFocused;
+      return compareTasks(a, b, phases);
+    });
+
+  const blockers = actionableTasks.filter((task) => task.status === "blocked");
+  const activeTasks = actionableTasks.filter((task) => task.status === "in_progress");
+  const reviewTasks = actionableTasks.filter((task) => task.status === "in_review");
+  const awaitingUserTasks = actionableTasks.filter((task) => task.awaitingUserConfirmation);
+  const verificationPendingTasks = actionableTasks.filter((task) => task.verificationPending);
+  const openTasks = actionableTasks.filter((task) => !closedStatuses.has(task.status));
+  const requiredOpenTasks = actionableTasks.filter((task) => task.required !== false && !closedStatuses.has(task.status));
+  const projectCompleted = requiredOpenTasks.length === 0 && actionableTasks.length > 0;
+  const agentInbox = config.normalizeAgentInbox(control.meta?.agentInbox);
+
+  const activePhase =
+    phases.find((phase) => requiredOpenTasks.some((task) => task.phase === phase.id)) ||
+    (projectCompleted ? phases[phases.length - 1] : phases[0]);
+
+  const phaseStats = phases.map((phase) => {
+    const phaseTasks = actionableTasks.filter((task) => task.phase === phase.id && task.required !== false);
+    const completed = phaseTasks.filter((task) => task.status === "completed").length;
+    const closed = phaseTasks.filter((task) => closedStatuses.has(task.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(treeTasks);
+
+  return {
+    tasks: treeTasks,
+    roots: roots.map((task) => task.id),
+    taskMap: Object.fromEntries(treeTasks.map((task) => [task.id, task])),
+    blockers,
+    activeTasks,
+    reviewTasks,
+    awaitingUserTasks,
+    verificationPendingTasks,
+    agentInbox,
+    readyTasks,
+    actionableTasks,
+    nextTask,
+    activePhase,
+    phaseStats,
+    projectCompleted,
+    circularDeps,
+    hierarchyCycles,
+    phantomDeps,
+    phantomParents,
+    openFindings: (control.findings || []).filter((finding) => finding.status === "open"),
+    resolvedFindings: (control.findings || []).filter((finding) => finding.status === "resolved"),
+    totals: {
+      all: actionableTasks.length,
+      completed: actionableTasks.filter((task) => task.status === "completed").length,
+      pending: actionableTasks.filter((task) => task.status === "pending").length,
+      inProgress: activeTasks.length,
+      inReview: reviewTasks.length,
+      blocked: blockers.length,
+      cancelled: actionableTasks.filter((task) => task.status === "cancelled").length,
+      parents: treeTasks.filter((task) => task.isParent).length,
+      awaitingUser: awaitingUserTasks.length,
+      verificationPending: verificationPendingTasks.length,
+      agentInboxPending: agentInbox.pending.length,
+    },
+  };
+}
+
+/* ── render ── */
+
+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];
+  const indent = options.hierarchy ? "  ".repeat(task.depth || 0) : "";
+  const sourceSuffix = task.sourceId ? ` [plan:${task.sourceId}]` : "";
+  const detachedSuffix = task.detached ? " [detached]" : "";
+  const parentSuffix = task.isParent ? ` [${task.childrenCount} child${task.childrenCount === 1 ? "" : "ren"}]` : "";
+  const executionSuffix = task.executionOwner ? ` [exec:${task.executionOwner}]` : "";
+  const awaitingSuffix = task.awaitingUserConfirmation ? " [await-user]" : "";
+  const verifySuffix = task.verificationPending ? " [verify]" : "";
+  return `${indent}- ${token} \`${task.id}\` [${task.priority}] ${task.title}${sourceSuffix}${detachedSuffix}${parentSuffix}${executionSuffix}${awaitingSuffix}${verifySuffix} (${phase.id} · ${phase.label} · ${task.stream})${detailSuffix}`;
+}
+
+function renderPlanSummary(control) {
+  const sources = control.meta?.plans?.sources || [];
+  if (!sources.length) return `- No imported plans.`;
+  return sources
+    .map((source) => `- [plan:${source.id}] ${source.title} (${source.adapter}) · status=${source.status} · warnings=${source.warnings} · conflicts=${source.conflicts}`)
+    .join("\n");
+}
+
+function renderAgentInboxSummary(state) {
+  const pending = state.agentInbox?.pending || [];
+  if (!pending.length) return `- ${t("doc.label.noAgentInbox")}`;
+  return pending
+    .slice(0, 8)
+    .map((item) => `- [${item.kind}] \`${item.taskId || "general"}\` ${item.message}`)
+    .join("\n");
+}
+
+function renderHierarchyOverview(state, phases) {
+  if (!state.tasks.length) return `- ${t("doc.label.noTasks")}`;
+  return state.tasks.map((task) => renderTask(task, phases, { hierarchy: true })).join("\n");
+}
+
+function renderTaskPlan(control) {
+  const phases = config.getPhases(control);
+  const state = derive(control);
   const blockersLabel = state.blockers.length
     ? state.blockers.map((t) => t.title).join("; ")
     : t("doc.label.noBlockers");
@@ -189,17 +661,21 @@ function renderTaskPlan(control) {
   const externalDecisions = (control.decisionsPending || []).length
     ? control.decisionsPending.map((d) => `- [${d.owner}] ${d.title} — ${d.impact}`).join("\n")
     : `- ${t("doc.label.noDecisions")}`;
-
-  const readyTasks = state.readyTasks.length
-    ? state.readyTasks.slice(0, 6).map((task) => renderTask(task, phases)).join("\n")
-    : `- ${t("doc.label.noReadyTasks")}`;
-
-  const phaseBlocks = phases.map((phase) => {
-    const phaseTasks = state.tasks.filter((task) => task.phase === phase.id);
-    const stats = state.phaseStats.find((s) => s.id === phase.id);
-    const lines = phaseTasks.length
-      ? phaseTasks.map((task) => renderTask(task, phases)).join("\n")
-      : `- ${t("doc.label.noTasks")}`;
+
+  const readyTasks = state.readyTasks.length
+    ? state.readyTasks.slice(0, 6).map((task) => renderTask(task, phases)).join("\n")
+    : `- ${t("doc.label.noReadyTasks")}`;
+
+  const hierarchyOverview = renderHierarchyOverview(state, phases);
+  const planSummary = renderPlanSummary(control);
+  const agentInboxSummary = renderAgentInboxSummary(state);
+
+  const phaseBlocks = phases.map((phase) => {
+    const phaseTasks = state.actionableTasks.filter((task) => task.phase === phase.id);
+    const stats = state.phaseStats.find((s) => s.id === phase.id);
+    const lines = phaseTasks.length
+      ? phaseTasks.map((task) => renderTask(task, phases)).join("\n")
+      : `- ${t("doc.label.noTasks")}`;
 
     const phaseStatus = phase.id === state.activePhase.id
       ? t("doc.label.phaseActive")
@@ -216,29 +692,44 @@ function renderTaskPlan(control) {
     ].join("\n");
   }).join("\n\n---\n\n");
 
-  return [
-    `# ${t("doc.header.taskPlan", { projectName: control.meta.projectName })}`,
-    "",
-    `> ${t("doc.autogenerated")}`,
-    "",
+  return [
+    `# ${t("doc.header.taskPlan", { projectName: control.meta.projectName })}`,
+    "",
+    AUTO_GENERATED_MARKER,
+    "",
+    `> ${t("doc.autogenerated")}`,
+    "",
     `## ${t("doc.section.operativeState")}`,
     `- ${t("doc.label.activePhase")}: ${state.activePhase.id} — ${state.activePhase.label} (${state.activePhase.index}/${phases.length})`,
     `- ${t("doc.label.currentFocus")}: ${control.meta.currentFocus}`,
-    `- ${t("doc.label.deliveryTarget")}: ${control.meta.deliveryTarget}`,
-    `- ${t("doc.label.blockers")}: ${blockersLabel}`,
-    `- ${t("doc.label.nextStep")}: ${nextStep}`,
-    "",
-    `### ${t("doc.section.externalDecisions")}`,
-    externalDecisions,
-    "",
-    `### ${t("doc.section.readyTasks")}`,
-    readyTasks,
-    "",
-    "---",
-    "",
-    phaseBlocks,
-  ].join("\n");
-}
+    `- ${t("doc.label.deliveryTarget")}: ${control.meta.deliveryTarget}`,
+    `- ${t("doc.label.blockers")}: ${blockersLabel}`,
+    `- ${t("doc.label.nextStep")}: ${nextStep}`,
+    `- Imported plans: ${(control.meta?.plans?.sources || []).length}`,
+    `- Unresolved plan conflicts: ${control.meta?.plans?.unresolvedConflicts || 0}`,
+    `- Agent inbox pending: ${state.totals.agentInboxPending}`,
+    `- Awaiting user confirmation: ${state.totals.awaitingUser}`,
+    "",
+    "### Plan Sources",
+    planSummary,
+    "",
+    "### Agent Coordination",
+    agentInboxSummary,
+    "",
+    `### ${t("doc.section.externalDecisions")}`,
+    externalDecisions,
+    "",
+    `### ${t("doc.section.readyTasks")}`,
+    readyTasks,
+    "",
+    "### Hierarchy",
+    hierarchyOverview,
+    "",
+    "---",
+    "",
+    phaseBlocks,
+  ].join("\n");
+}
 
 function renderProgress(control) {
   const phases = config.getPhases(control);
@@ -248,14 +739,17 @@ function renderProgress(control) {
     : t("doc.label.noBlockers");
   const nextStep = state.nextTask ? state.nextTask.title : t("doc.label.noOpenTasks");
   const lastTest = (control.checks || {}).lastTest || { status: "pending" };
-  const latestHistory = state.tasks
-    .flatMap((task) => (task.history || []).map((entry) => ({ ...entry, taskId: task.id, taskTitle: task.title })))
-    .sort((a, b) => (a.at < b.at ? 1 : -1))
-    .slice(0, 8);
-
-  const activeLines = state.activeTasks.length
-    ? state.activeTasks.map((task) => renderTask(task, phases)).join("\n")
-    : `- ${t("doc.label.noActiveTasks")}`;
+  const latestHistory = state.tasks
+    .flatMap((task) => (task.history || []).map((entry) => ({ ...entry, taskId: task.id, taskTitle: task.title })))
+    .sort((a, b) => (a.at < b.at ? 1 : -1))
+    .slice(0, 8);
+  const planActivity = latestHistory
+    .filter((entry) => String(entry.action || "").startsWith("plan_") || entry.action === "detach_from_plan")
+    .slice(0, 5);
+
+  const activeLines = state.activeTasks.length
+    ? state.activeTasks.map((task) => renderTask(task, phases)).join("\n")
+    : `- ${t("doc.label.noActiveTasks")}`;
 
   const reviewLines = state.reviewTasks.length
     ? state.reviewTasks.map((task) => renderTask(task, phases)).join("\n")
@@ -264,27 +758,33 @@ function renderProgress(control) {
   const blockerLines = state.blockers.length
     ? state.blockers.map((task) => renderTask(task, phases)).join("\n")
     : `- ${t("doc.label.noActiveBlockers")}`;
-
-  const historyLines = latestHistory.length
-    ? latestHistory.map((e) => `- [${e.at.slice(0, 10)}] \`${e.taskId}\` ${e.action}${e.note ? ` — ${e.note}` : ""}`).join("\n")
-    : `- ${t("doc.label.noHistory")}`;
-
-  const milestoneLines = (control.milestones || [])
-    .map((m) => {
-      const items = m.items.map((item) => `- ${item}`).join("\n");
-      return [`### [${m.date}] — ${m.title}`, items].join("\n");
+
+  const historyLines = latestHistory.length
+    ? latestHistory.map((e) => `- [${e.at.slice(0, 10)}] \`${e.taskId}\` ${e.action}${e.note ? ` — ${e.note}` : ""}`).join("\n")
+    : `- ${t("doc.label.noHistory")}`;
+  const planActivityLines = planActivity.length
+    ? planActivity.map((e) => `- [${e.at.slice(0, 10)}] \`${e.taskId}\` ${e.action}${e.note ? ` — ${e.note}` : ""}`).join("\n")
+    : "- No plan imports yet.";
+  const agentInboxLines = renderAgentInboxSummary(state);
+
+  const milestoneLines = (control.milestones || [])
+    .map((m) => {
+      const items = m.items.map((item) => `- ${item}`).join("\n");
+      return [`### [${m.date}] — ${m.title}`, items].join("\n");
     })
     .join("\n\n");
 
-  return [
-    `# ${t("doc.header.progress", { projectName: control.meta.projectName })}`,
-    "",
-    `> ${t("doc.autogenerated")}`,
-    "",
+  return [
+    `# ${t("doc.header.progress", { projectName: control.meta.projectName })}`,
+    "",
+    AUTO_GENERATED_MARKER,
+    "",
+    `> ${t("doc.autogenerated")}`,
+    "",
     `## ${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)}`,
     "",
@@ -295,37 +795,72 @@ function renderProgress(control) {
     `- ${t("doc.label.completedTasks")}: ${state.totals.completed}`,
     `- ${t("doc.label.inProgressTasks")}: ${state.totals.inProgress}`,
     `- ${t("doc.label.inReviewTasks")}: ${state.totals.inReview}`,
-    `- ${t("doc.label.pendingTasks")}: ${state.totals.pending}`,
-    `- ${t("doc.label.blockedTasks")}: ${state.totals.blocked}`,
-    "",
-    `### ${t("doc.section.activeTasks")}`,
-    activeLines,
+    `- ${t("doc.label.pendingTasks")}: ${state.totals.pending}`,
+    `- ${t("doc.label.blockedTasks")}: ${state.totals.blocked}`,
+    `- ${t("doc.label.awaitingUserTasks")}: ${state.totals.awaitingUser}`,
+    `- ${t("doc.label.agentInboxPending")}: ${state.totals.agentInboxPending}`,
+    "",
+    `### ${t("doc.section.activeTasks")}`,
+    activeLines,
     "",
     `### ${t("doc.section.reviewTasks")}`,
     reviewLines,
     "",
     `### ${t("doc.section.activeBlockers")}`,
     blockerLines,
-    "",
-    `### ${t("doc.section.recentActivity")}`,
-    historyLines,
-    "",
-    "---",
-    "",
-    `## ${t("doc.section.milestones")}`,
-    "",
-    milestoneLines,
+    "",
+    `### ${t("doc.section.recentActivity")}`,
+    historyLines,
+    "",
+    "### Agent Coordination",
+    agentInboxLines,
+    "",
+    "### Plan Activity",
+    planActivityLines,
+    "",
+    "---",
+    "",
+    `## ${t("doc.section.milestones")}`,
+    "",
+    milestoneLines,
   ].join("\n");
 }
 
-function renderFindings(control) {
-  const state = derive(control);
-  const openLines = state.openFindings.length
-    ? state.openFindings
-        .map((f) =>
-          `### [${f.severity.toUpperCase()}] ${f.title}\n- ${t("doc.label.findingStatus")}: ${t("doc.label.findingOpen")}\n- ${t("doc.label.findingDetail")}: ${f.detail}\n- ${t("doc.label.findingImpact")}: ${f.impact}`
-        )
-        .join("\n\n")
+function renderFindings(control) {
+  const state = derive(control);
+  const planFindings = [];
+  if (state.hierarchyCycles.length) {
+    planFindings.push({
+      severity: "high",
+      title: "Hierarchy cycle detected",
+      detail: `Tasks with parent cycles: ${state.hierarchyCycles.join(", ")}`,
+      impact: "Parent rollups and tree rendering are degraded until hierarchy is corrected.",
+    });
+  }
+  if (state.phantomParents.length) {
+    planFindings.push({
+      severity: "medium",
+      title: "Tasks with missing parents",
+      detail: state.phantomParents.map((entry) => `${entry.taskId} -> ${entry.missingParentId}`).join("; "),
+      impact: "Affected tasks are promoted to roots in the derived tree.",
+    });
+  }
+  if (control.meta?.plans?.unresolvedConflicts) {
+    planFindings.push({
+      severity: "medium",
+      title: "Imported plans have unresolved conflicts",
+      detail: `${control.meta.plans.unresolvedConflicts} linked plan conflict(s) remain unresolved.`,
+      impact: "Applying previews with conflict policy 'abort' will be blocked.",
+    });
+  }
+
+  const openFindings = [...planFindings, ...state.openFindings];
+  const openLines = openFindings.length
+    ? openFindings
+        .map((f) =>
+          `### [${f.severity.toUpperCase()}] ${f.title}\n- ${t("doc.label.findingStatus")}: ${t("doc.label.findingOpen")}\n- ${t("doc.label.findingDetail")}: ${f.detail}\n- ${t("doc.label.findingImpact")}: ${f.impact}`
+        )
+        .join("\n\n")
     : t("doc.label.noFindings");
 
   const resolvedLines = state.resolvedFindings.length
@@ -336,11 +871,13 @@ function renderFindings(control) {
         .join("\n\n")
     : t("doc.label.noResolvedFindings");
 
-  return [
-    `# ${t("doc.header.findings", { projectName: control.meta.projectName })}`,
-    "",
-    `> ${t("doc.autogenerated")}`,
-    "",
+  return [
+    `# ${t("doc.header.findings", { projectName: control.meta.projectName })}`,
+    "",
+    AUTO_GENERATED_MARKER,
+    "",
+    `> ${t("doc.autogenerated")}`,
+    "",
     `## ${t("doc.section.openFindings")}`,
     "",
     openLines,
@@ -371,44 +908,111 @@ function getDocDrift(root, control) {
     .map(([name]) => name);
 }
 
-function syncDocs(root, control) {
+function syncDocs(root, control, options = {}) {
   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`);
-}
-
-/* ── 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 }));
-
-  const actionMap = { start: "in_progress", review: "in_review", complete: "completed", done: "completed", block: "blocked", pending: "pending", cancel: "cancelled" };
-
-  if (action === "note") {
-    task.history = task.history || [];
-    task.history.push({ at: nowIso(), action: "note", note: note || t("cli.emptyNote") });
-  } else {
-    const nextStatus = actionMap[action];
-    if (!nextStatus) throw new Error(t("cli.actionNotSupported", { action }));
-
-    task.status = nextStatus;
-    if (nextStatus === "blocked") {
-      task.blocker = note || task.blocker || t("cli.undocumentedBlocker");
-    } else {
-      delete task.blocker;
-    }
-    task.history = task.history || [];
-    task.history.push({ at: nowIso(), action, note: note || "" });
+  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(AUTO_GENERATED_MARKER) || existing.includes(t("doc.autogenerated"));
+      if (!isAutoGenerated && existing.trim()) {
+        console.error(t("control.docsOverwriteWarning", { file: path.basename(filePath) }));
+        continue;
+      }
+    }
+    writeText(filePath, `${content}\n`);
   }
+}
 
-  config.saveControl(context, control);
-  syncDocs(context, control);
-  refreshRepoRuntime(context, { quiet: true });
+/* ── task management ── */
+
+function taskHasChildren(controlState, taskId) {
+  return (controlState.tasks || []).some((task) => String(task.parentId || "").trim() === taskId);
+}
+
+function setTaskStatus(root, control, taskId, status, note, options = {}) {
+  const context = config.ensureContext(root);
+  const task = control.tasks.find((item) => item.id === taskId);
+  if (!task) throw new Error(t("cli.taskNotFound", { taskId }));
+  if (taskHasChildren(control, taskId)) {
+    throw new Error(`Task '${taskId}' is a parent task. Update its leaf tasks instead; parent status is rolled up automatically.`);
+  }
+  const nextStatus = String(status || "").trim();
+  if (!nextStatus) throw new Error(t("cli.actionNotSupported", { action: status }));
+  if (task.status === nextStatus) {
+    setTaskExecutionContext(task, {
+      owner: options.owner,
+      actor: options.actor || "system",
+      source: options.source || "system",
+      sessionId: Object.prototype.hasOwnProperty.call(options, "sessionId") ? options.sessionId : undefined,
+      verificationPending: task.execution?.verificationPending,
+      awaitingUserConfirmation: task.execution?.awaitingUserConfirmation,
+    });
+    config.saveControl(context, control);
+    syncDocs(context, control);
+    refreshRepoRuntime(context, { quiet: true });
+    return task;
+  }
+
+  applyTaskStateTransition(control, task, {
+    status: nextStatus,
+    action: options.historyAction || "edit",
+    note,
+  }, options);
+
+  config.saveControl(context, control);
+  syncDocs(context, control);
+  refreshRepoRuntime(context, { quiet: true });
+  return task;
+}
+
+function updateTask(root, control, action, taskId, note, options = {}) {
+  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" };
+
+  if (action === "note") {
+    task.history = task.history || [];
+    task.history.push({ at: nowIso(), action: "note", note: note || t("cli.emptyNote") });
+    setTaskExecutionContext(task, {
+      owner: options.owner,
+      actor: options.actor || "agent",
+      source: options.source || "cli",
+      sessionId: Object.prototype.hasOwnProperty.call(options, "sessionId") ? options.sessionId : undefined,
+    });
+  } else {
+    const nextStatus = actionMap[action];
+    if (!nextStatus) throw new Error(t("cli.actionNotSupported", { action }));
+    if (taskHasChildren(control, taskId)) {
+      throw new Error(`Task '${taskId}' is a parent task. Update its leaf tasks instead; parent status is rolled up automatically.`);
+    }
+
+    if (task.status === nextStatus) {
+      console.log(t("control.taskAlreadyStatus", { taskId, status: nextStatus }));
+      return;
+    }
+    applyTaskStateTransition(control, task, {
+      status: nextStatus,
+      action,
+      note,
+    }, {
+      ...options,
+      actor: options.actor || "agent",
+      source: options.source || "cli",
+    });
+  }
+
+  config.saveControl(context, control);
+  syncDocs(context, control);
+  refreshRepoRuntime(context, { quiet: true });
 }
 
 /* ── CLI commands ── */
@@ -422,103 +1026,190 @@ function initLocale(root) {
   }
 }
 
-function cmdStatus(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const control = config.loadControl(context);
-  const state = derive(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}`);
-  if (context.layout === "split") {
-    console.log(`App: ${context.appRoot}`);
-    console.log(`Ops: ${context.opsRoot}`);
-  }
-  if (control.meta?.opera?.bootstrap?.status) {
-    console.log(t("cli.status.bootstrap", { status: control.meta.opera.bootstrap.status, locale: config.getLocale(control) }));
-    if (control.meta.opera.bootstrap.mode) {
-      console.log(`Bootstrap mode: ${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.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(t("cli.status.layout", { layout: context.layout, workspace: context.workspaceRoot }));
+  if (context.layout === "split") {
+    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: formatBootstrapStatus(control.meta.opera.bootstrap.status),
+      locale: config.getLocale(control),
+    }));
+    if (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(t("cli.status.bootstrapReason", { value: formatBootstrapReason(control.meta.opera.bootstrap.routeReason) }));
+    }
+  }
   console.log(t("cli.status.tasks", {
     completed: state.totals.completed, inProgress: state.totals.inProgress,
     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("");
-  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("");
-  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(`- ${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.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("");
-  const syncStatus = drift.length
-    ? t("cli.status.docsSyncedNo", { files: drift.join(", ") })
-    : t("cli.status.docsSyncedYes");
-  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);
-  if (!ready.length) {
-    console.log(t("cli.noReadyTasks"));
-    return;
+  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.agentInbox"));
+  if (state.agentInbox.pending.length) {
+    state.agentInbox.pending.slice(0, 5).forEach((item) => console.log(`- [${item.kind}] ${item.taskId || "general"} — ${item.message}`));
+  } else {
+    console.log(`- ${t("cli.status.noAgentInbox")}`);
+  }
+  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(`- ${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(", ") })
+    : t("cli.status.docsSyncedYes");
+  console.log(t("cli.status.docsSynced", { status: syncStatus }));
+  try {
+    const quality = require("./quality");
+    const snapshot = quality.buildQualitySnapshot(context, control);
+    console.log("");
+    console.log(t("quality.statusBlock.title"));
+    console.log(`- ${t("quality.statusBlock.status")}: ${quality.formatQualityStatus(snapshot.report.summary.overallStatus)}`);
+    console.log(`- ${t("quality.statusBlock.phaseReadiness")}: ${quality.formatQualityStatus(snapshot.phaseReadiness.status)}`);
+    console.log(`- ${t("quality.statusBlock.releaseReadiness")}: ${quality.formatQualityStatus(snapshot.releaseReadiness.status)}`);
+    if (snapshot.releaseReadiness.blockers.length) {
+      snapshot.releaseReadiness.blockers.slice(0, 3).forEach((item) => {
+        console.log(`- ${t("quality.statusBlock.blocker")}: ${item.id} — ${item.message}`);
+      });
+    }
+  } catch (_error) {
+    // Quality is complementary; status should still work if it cannot be computed.
+  }
+}
+
+function cmdNext(root) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const control = config.loadControl(context);
+  const state = derive(control);
+  const printTasks = (tasks) => {
+    tasks.forEach((task, i) => {
+      console.log(`${i + 1}. ${task.title}`);
+      console.log(`   id: ${task.id}`);
+      console.log(`   ${t("cli.next.phase")}: ${task.phase} · ${t("cli.next.priority")}: ${task.priority} · ${t("cli.next.stream")}: ${task.stream}`);
+      if (task.summary) console.log(`   ${t("cli.next.summary")}: ${task.summary}`);
+    });
+  };
+
+  if (state.circularDeps.length) {
+    console.log(t("control.circularDependency", { taskIds: state.circularDeps.join(", ") }));
+  }
+  const active = state.activeTasks.slice(0, 5);
+  const ready = state.readyTasks.slice(0, 10);
+  if (active.length) {
+    console.log(t("cli.next.activeTasks"));
+    printTasks(active);
+    if (ready.length) {
+      console.log("");
+      console.log(t("cli.next.readyQueue"));
+      printTasks(ready.slice(0, 5));
+    }
+    return;
+  }
+  if (!ready.length) {
+    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;
+  }
+  printTasks(ready);
+}
+
+function cmdSync(root, args) {
+  const context = config.ensureContext(root);
+  initLocale(context);
+  const control = config.loadControl(context);
+  if (control.__trackopsMigrated) {
+    config.saveControl(context, control);
+  }
+  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);
   }
-  ready.forEach((task, i) => {
-    console.log(`${i + 1}. ${task.title}`);
-    console.log(`   id: ${task.id}`);
-    console.log(`   ${t("cli.next.phase")}: ${task.phase} · ${t("cli.next.priority")}: ${task.priority} · ${t("cli.next.stream")}: ${task.stream}`);
-    if (task.summary) console.log(`   ${t("cli.next.summary")}: ${task.summary}`);
-  });
-}
-
-function cmdSync(root) {
-  const context = config.ensureContext(root);
-  initLocale(context);
-  const control = config.loadControl(context);
   env.syncEnvironment(context, control);
-  syncDocs(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"));
 }
@@ -530,12 +1221,12 @@ function cmdRefreshRepo(root, args) {
 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 }));
-}
+  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(), { actor: "agent", source: "cli" });
+  console.log(t("cli.taskUpdated", { taskId, action }));
+}
 
 function cmdInstallHooks(root) {
   const context = config.ensureContext(root);
@@ -581,10 +1272,14 @@ function cmdHelp() {
   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("  task <action> <id> [note]");
+  console.log(`    ${t("cli.help.task.desc")}`);
+  console.log("  plan scan|import|show|apply|list|unlink");
+  console.log(`    ${t("cli.help.plan.desc")}`);
+  console.log("  quality status|verify|phase-readiness|release-readiness|promote-readiness|waiver");
+  console.log(`    ${t("cli.help.quality.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")}`);
@@ -593,11 +1288,14 @@ function cmdHelp() {
   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.globalWorkflow"));
-  console.log(`  ${t("cli.help.globalWorkflow.line1")}`);
-  console.log(`  ${t("cli.help.globalWorkflow.line2")}`);
+  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) ── */
@@ -611,20 +1309,22 @@ function forProject(root) {
     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),
+    syncDocs: (ctrl) => syncDocs(context, ctrl),
+    updateTask: (ctrl, action, id, note, options) => updateTask(context, ctrl, action, id, note, options),
+    setTaskStatus: (ctrl, id, status, note, options) => setTaskStatus(context, ctrl, id, status, note, options),
+    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,
-  forProject, statusLabel, renderTask, getPhaseInfo,
+module.exports = {
+  buildDocMap, derive, getDocDrift, getRepoSnapshot, refreshRepoRuntime, syncDocs, updateTask,
+  setTaskStatus, ensureAgentInbox, upsertAgentInstruction, resolveAgentInstructions,
+  forProject, statusLabel, renderTask, getPhaseInfo,
   cmdStatus, cmdNext, cmdSync, cmdRefreshRepo, cmdTask, cmdInstallHooks, cmdHelp,
   PRIORITY_ORDER, STATUS_ORDER, STATUS_ICONS, CHECK_ICONS,
 };