kanbango 3.6.2 → 5.1.0

package/kanban.js

@@ -1,9 +1,21 @@
 const fs = require('fs').promises;
 const path = require('path');
 
-const BACKLOG = path.join(process.cwd(), 'backlog');
-const EPICS_DIR = path.join(BACKLOG, 'epics');
-const COLS = ['active', 'planned', 'icebox', 'testing', 'review', 'done'];
+function backlogDir() {
+  return path.join(process.cwd(), 'backlog');
+}
+
+function epicsDir() {
+  return path.join(backlogDir(), 'epics');
+}
+
+const BOARD_LOCK_NAME = '.board.lock';
+const BOARD_LOCK_TIMEOUT_MS = 2000;
+const BOARD_LOCK_POLL_MS = 50;
+/** All physical column dirs that may exist on disk (including disabled gates). */
+const KNOWN_COLS = ['active', 'planned', 'icebox', 'testing', 'review', 'done'];
+/** Active columns for validation / MCP / create — mutated by applyBoardLayout. */
+let COLS = KNOWN_COLS.slice();
 const STATUS_MAP = {
   active: 'in_progress',
   planned: 'planned',
@@ -12,11 +24,12 @@ const STATUS_MAP = {
   review: 'review',
   done: 'done'
 };
-const WORKFLOW_STAGES = ['testing', 'review'];
+/** Gate stages that may spawn agents — subset of active COLS. */
+let WORKFLOW_STAGES = ['testing', 'review'];
 const WORKFLOW_STATUSES = ['idle', 'running', 'pass', 'fail', 'blocked'];
 const EVIDENCE_VERDICTS = ['pass', 'fail', 'blocked', ''];
-// Agent/human move contract. Same column is always a no-op.
-const COLUMN_TRANSITIONS = {
+// Agent/human move contract. Same column is always a no-op. Mutated by applyBoardLayout.
+let COLUMN_TRANSITIONS = {
   icebox: ['planned'],
   planned: ['active', 'icebox', 'testing'],
   active: ['planned', 'testing', 'icebox'],
@@ -24,8 +37,31 @@ const COLUMN_TRANSITIONS = {
   review: ['active', 'done'],
   done: ['active']
 };
+
+/**
+ * Apply project board layout from backlog/kanbango.json (via workflow.ensureBoardConfig).
+ * Does not create/delete dirs; only changes which columns are legal and which transitions apply.
+ */
+function applyBoardLayout({ cols, transitions, workflowStages } = {}) {
+  if (Array.isArray(cols) && cols.length > 0) {
+    COLS = cols.slice();
+  }
+  if (transitions && typeof transitions === 'object' && !Array.isArray(transitions)) {
+    COLUMN_TRANSITIONS = {};
+    for (const [from, targets] of Object.entries(transitions)) {
+      COLUMN_TRANSITIONS[from] = Array.isArray(targets) ? targets.slice() : [];
+    }
+  }
+  if (Array.isArray(workflowStages)) {
+    WORKFLOW_STAGES = workflowStages.slice();
+  }
+  // Keep module.exports live references in sync for consumers that cached the export object.
+  module.exports.COLS = COLS;
+  module.exports.COLUMN_TRANSITIONS = COLUMN_TRANSITIONS;
+  module.exports.WORKFLOW_STAGES = WORKFLOW_STAGES;
+}
 const VIEW_FIELDS = {
-  summary: ['task_number', 'title', 'column', 'epic_id', 'epic_group', 'created', 'progress'],
+  summary: ['id', 'task_number', 'title', 'column', 'epic_id', 'progress', 'blocked'],
   planning: [
     'task_number',
     'title',
@@ -40,28 +76,24 @@ const VIEW_FIELDS = {
     'in_scope',
     'out_of_scope',
     'acceptance_criteria',
-    'test_cases'
+    'test_cases',
+    'depends_on',
+    'blocked',
+    'unmet_dependencies',
+    'blocks'
   ],
   execution: [
+    'id',
     'task_number',
     'title',
     'column',
     'epic_id',
-    'epic_group',
-    'epic_goals',
-    'created',
     'progress',
-    'description',
-    'specs',
-    'in_scope',
-    'out_of_scope',
-    'acceptance_criteria',
-    'test_cases',
+    'current_subtask',
     'subtasks',
-    'adr',
-    'evidence',
-    'plan',
-    'workflow'
+    'workflow',
+    'files',
+    'blocked'
   ],
   full: [
     'task_number',
@@ -83,7 +115,12 @@ const VIEW_FIELDS = {
     'notes',
     'evidence',
     'plan',
-    'workflow'
+    'workflow',
+    'depends_on',
+    'files',
+    'blocked',
+    'unmet_dependencies',
+    'blocks'
   ]
 };
 
@@ -148,10 +185,18 @@ function createKanbanError(code, message, hint, details = {}, retryable = false,
 }
 
 // Serialize board mutations so concurrent create/move/update cannot race on ids or paths.
+// mutationTail = in-process; backlog/.board.lock = cross-process.
 let mutationTail = Promise.resolve();
 
 function withBoardLock(fn) {
-  const run = mutationTail.then(() => fn());
+  const run = mutationTail.then(async () => {
+    const owner = await acquireBoardLock();
+    try {
+      return await fn();
+    } finally {
+      await releaseBoardLock(owner);
+    }
+  });
   mutationTail = run.then(() => undefined, () => undefined);
   return run;
 }
@@ -184,6 +229,119 @@ async function writeFileAtomic(filePath, payload, { exclusive = false } = {}) {
   }
 }
 
+function boardLockPath() {
+  return path.join(backlogDir(), BOARD_LOCK_NAME);
+}
+
+function newBoardLockOwner() {
+  return {
+    pid: process.pid,
+    token: `${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`,
+    started: new Date().toISOString()
+  };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error.code === 'ESRCH') return false;
+    return true;
+  }
+}
+
+function boardLockedError(details = {}) {
+  return createKanbanError(
+    'BOARD_LOCKED',
+    'Board is locked by another process',
+    'Retry the mutation after the other process finishes writing',
+    details,
+    true,
+    409
+  );
+}
+
+async function readBoardLockOwner() {
+  let raw;
+  try {
+    raw = await fs.readFile(boardLockPath(), 'utf-8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    return null;
+  }
+  try {
+    const data = JSON.parse(raw);
+    const pid = Number(data && data.pid);
+    const token = data && typeof data.token === 'string' ? data.token : '';
+    if (!Number.isInteger(pid) || pid <= 0 || !token) return null;
+    return { pid, token, started: data.started };
+  } catch {
+    return null;
+  }
+}
+
+async function tryPublishBoardLock(owner) {
+  await ensureBacklogDir();
+  try {
+    await writeFileAtomic(boardLockPath(), JSON.stringify(owner) + '\n', { exclusive: true });
+    return true;
+  } catch (error) {
+    if (error.code === 'EEXIST') return false;
+    throw error;
+  }
+}
+
+async function stealDeadBoardLock(expectedToken) {
+  const current = await readBoardLockOwner();
+  if (!current || current.token !== expectedToken) return false;
+  if (isPidAlive(current.pid)) return false;
+  const again = await readBoardLockOwner();
+  if (!again || again.token !== expectedToken) return false;
+  if (isPidAlive(again.pid)) return false;
+  try {
+    await fs.unlink(boardLockPath());
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return true;
+}
+
+async function acquireBoardLock() {
+  const owner = newBoardLockOwner();
+  const deadline = Date.now() + BOARD_LOCK_TIMEOUT_MS;
+  while (Date.now() <= deadline) {
+    if (await tryPublishBoardLock(owner)) return owner;
+    await sleep(BOARD_LOCK_POLL_MS);
+  }
+  const observed = await readBoardLockOwner();
+  if (observed && observed.token && !isPidAlive(observed.pid)) {
+    await stealDeadBoardLock(observed.token);
+    if (await tryPublishBoardLock(owner)) return owner;
+  } else if (observed === undefined) {
+    if (await tryPublishBoardLock(owner)) return owner;
+  }
+  throw boardLockedError({
+    timeout_ms: BOARD_LOCK_TIMEOUT_MS,
+    holder_pid: observed && observed.pid
+  });
+}
+
+async function releaseBoardLock(owner) {
+  if (!owner || !owner.token) return;
+  const current = await readBoardLockOwner();
+  if (!current || current.token !== owner.token) return;
+  try {
+    await fs.unlink(boardLockPath());
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
 function todayIso() {
   return new Date().toISOString().split('T')[0];
 }
@@ -208,6 +366,276 @@ function normalizeStringArray(value) {
     .filter(Boolean);
 }
 
+function assertIsArray(value, field, message, hint) {
+  if (Array.isArray(value)) return;
+  throw createKanbanError(
+    'VALIDATION_ERROR',
+    message,
+    hint,
+    { field },
+    false,
+    400
+  );
+}
+
+function requireStringArray(value, field) {
+  assertIsArray(
+    value,
+    field,
+    `${field} must be an array of strings`,
+    `Send ${field} as an array`
+  );
+  return normalizeStringArray(value);
+}
+
+function requireNonEmptyTitle(value) {
+  const title = normalizeString(value);
+  if (!title) {
+    throw createKanbanError(
+      'VALIDATION_ERROR',
+      'title must be a non-empty string',
+      'Send a non-empty title or omit the field',
+      { field: 'title' },
+      false,
+      400
+    );
+  }
+  return title;
+}
+
+function applyAdrPatch(existing, adr) {
+  if (Array.isArray(adr)) return normalizeAdr(adr);
+  return appendAdrEntry(existing, adr);
+}
+
+function normalizeTaskIdRef(value) {
+  const raw = normalizeString(value);
+  if (!raw) return '';
+  if (/^\d+$/.test(raw)) return raw.padStart(3, '0');
+  return raw;
+}
+
+function uniqueNormalizedStrings(value, mapItem) {
+  if (!Array.isArray(value)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const item of value) {
+    const next = mapItem(item);
+    if (!next || seen.has(next)) continue;
+    seen.add(next);
+    out.push(next);
+  }
+  return out;
+}
+
+function normalizeDependsOn(value) {
+  return uniqueNormalizedStrings(value, normalizeTaskIdRef);
+}
+
+function normalizeFiles(value) {
+  return uniqueNormalizedStrings(value, normalizeString);
+}
+
+function isWorkColumn(column) {
+  return column === 'active' || WORKFLOW_STAGES.includes(column);
+}
+
+function unmetDependencies(task, allTasks) {
+  const deps = Array.isArray(task && task.depends_on) ? task.depends_on : [];
+  if (deps.length === 0) return [];
+  const byId = new Map();
+  for (const other of allTasks || []) {
+    byId.set(other.id, other);
+  }
+  const unmet = [];
+  for (const depId of deps) {
+    const dep = byId.get(depId);
+    if (!dep || dep.column !== 'done') {
+      unmet.push({
+        id: depId,
+        column: dep ? dep.column : null,
+        missing: !dep
+      });
+    }
+  }
+  return unmet;
+}
+
+function assertUnblockedForColumn(task, targetColumn, allTasks) {
+  if (!isWorkColumn(targetColumn)) return;
+  const unmet = unmetDependencies(task, allTasks);
+  if (unmet.length === 0) return;
+  const labels = unmet.map((item) => (
+    item.missing ? `${item.id} (missing)` : `${item.id} (${item.column})`
+  ));
+  throw createKanbanError(
+    'TASK_BLOCKED',
+    `Task ${task.id} is blocked by incomplete tasks: ${labels.join(', ')}`,
+    'Finish dependency tasks (move them to done) or remove them from depends_on',
+    {
+      task_id: task.id,
+      unmet_dependencies: unmet.map((item) => item.id),
+      blocked_by: unmet
+    },
+    false,
+    400
+  );
+}
+
+function computeBlocks(taskId, allTasks) {
+  if (!taskId) return [];
+  return (allTasks || [])
+    .filter((other) => other.id !== taskId && (other.depends_on || []).includes(taskId))
+    .map((other) => other.id)
+    .sort();
+}
+
+function findDependencyCycle(taskId, dependsOn, allTasks) {
+  const graph = new Map();
+  for (const other of allTasks || []) {
+    graph.set(other.id, (other.depends_on || []).slice());
+  }
+  graph.set(taskId, Array.isArray(dependsOn) ? dependsOn.slice() : []);
+
+  const visiting = new Set();
+  const visited = new Set();
+  const stack = [];
+
+  function dfs(id) {
+    if (visiting.has(id)) {
+      const start = stack.indexOf(id);
+      return stack.slice(start).concat(id);
+    }
+    if (visited.has(id)) return null;
+    visiting.add(id);
+    stack.push(id);
+    for (const depId of graph.get(id) || []) {
+      const cycle = dfs(depId);
+      if (cycle) return cycle;
+    }
+    stack.pop();
+    visiting.delete(id);
+    visited.add(id);
+    return null;
+  }
+
+  return dfs(taskId);
+}
+
+function assertNoDependencyCycle(taskId, dependsOn, allTasks) {
+  const cycle = findDependencyCycle(taskId, dependsOn, allTasks);
+  if (!cycle) return;
+  throw createKanbanError(
+    'CIRCULAR_DEPENDENCY',
+    `Circular dependency: ${cycle.join(' → ')}`,
+    'Remove one of the depends_on links that closes the loop',
+    { cycle },
+    false,
+    400
+  );
+}
+
+function newlyUnblockedTasks(doneTaskId, allTasks) {
+  return (allTasks || [])
+    .filter((other) => other.id !== doneTaskId && (other.depends_on || []).includes(doneTaskId))
+    .filter((other) => unmetDependencies(other, allTasks).length === 0)
+    .map((other) => other.id)
+    .sort();
+}
+
+function firstEnabledGateColumn() {
+  if (COLS.includes('testing')) return 'testing';
+  if (COLS.includes('review')) return 'review';
+  return 'done';
+}
+
+function evidenceHasProof(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  return Boolean(
+    normalizeString(entry.diff)
+    || normalizeString(entry.summary)
+    || normalizeString(entry.test_command)
+  );
+}
+
+function hasProofEvidence(evidence) {
+  return normalizeEvidence(evidence).some(evidenceHasProof);
+}
+
+function requiresEvidenceForColumn(toColumn) {
+  if (toColumn === 'testing') return COLS.includes('testing');
+  if (toColumn === 'review') return COLS.includes('review');
+  if (toColumn === 'done') return COLS.includes('testing') || COLS.includes('review');
+  return false;
+}
+
+function assertEvidenceForGate(fromTask, toTask) {
+  const fromColumn = fromTask && fromTask.column;
+  const toColumn = toTask && toTask.column;
+  if (!toColumn || fromColumn === toColumn) return;
+  if (!requiresEvidenceForColumn(toColumn)) return;
+
+  const status = toTask.workflow && toTask.workflow.status;
+  const fromGate = fromColumn === 'testing' || fromColumn === 'review';
+  if (fromGate && (status === 'fail' || status === 'blocked')) {
+    throw createKanbanError(
+      'EVIDENCE_REQUIRED',
+      `Cannot move task ${toTask.id} from ${fromColumn} to ${toColumn} while workflow is ${status}`,
+      'Move back to active, add new evidence (diff|summary|test_command), then re-enter the gate',
+      {
+        task_id: toTask.id,
+        from: fromColumn,
+        to: toColumn,
+        workflow_status: status
+      },
+      false,
+      400
+    );
+  }
+
+  if (!hasProofEvidence(toTask.evidence)) {
+    throw createKanbanError(
+      'EVIDENCE_REQUIRED',
+      `Cannot move task ${toTask.id} from ${fromColumn} to ${toColumn} without evidence`,
+      'Add evidence with at least one of diff, summary, or test_command before entering the gate',
+      {
+        task_id: toTask.id,
+        from: fromColumn,
+        to: toColumn,
+        missing: ['evidence'],
+        need: 'diff|summary|test_command'
+      },
+      false,
+      400
+    );
+  }
+}
+
+function nextMoveAction() {
+  const gate = firstEnabledGateColumn();
+  if (gate === 'testing') return 'move_testing';
+  if (gate === 'review') return 'move_review';
+  return 'move_done';
+}
+
+function resolveNextAction(task, mode) {
+  if (mode === 'start') return 'start';
+  if (mode === 'idle') return 'idle';
+  const status = task.workflow && task.workflow.status;
+  if (
+    (task.column === 'testing' || task.column === 'review')
+    && (status === 'fail' || status === 'blocked')
+  ) {
+    return 'fix_gate';
+  }
+  if (currentSubtask(task)) return 'advance';
+  if (!hasProofEvidence(task.evidence)) return 'evidence';
+  if (task.column === 'active') return nextMoveAction();
+  if (task.column === 'testing' && COLS.includes('review')) return 'move_review';
+  if (task.column === 'testing' || task.column === 'review') return 'move_done';
+  return 'implement';
+}
+
 function isPresentCreateField(field, value) {
   if (
     field === 'description'
@@ -385,7 +813,8 @@ function normalizeTask(task) {
   const normalized = {
     id,
     title: stripTitlePrefix(task.title || id),
-    column: COLS.includes(task.column) ? task.column : 'planned',
+    // Accept any known physical column so disabled-gate cards stay readable until migrated.
+    column: KNOWN_COLS.includes(task.column) ? task.column : 'planned',
     epic_id: epicId,
     epic_group: epicId ? (epicGroup === '—' ? epicId : epicGroup) : (epicGroup === '—' ? '—' : epicGroup),
     created: normalizeString(task.created) || todayIso(),
@@ -401,6 +830,8 @@ function normalizeTask(task) {
     plan: normalizePlan(task.plan),
     evidence: normalizeEvidence(task.evidence),
     workflow: normalizeWorkflow(task.workflow),
+    depends_on: normalizeDependsOn(task.depends_on).filter((depId) => depId !== id),
+    files: normalizeFiles(task.files),
     task_number: extractTaskNumber(id)
   };
 
@@ -428,6 +859,8 @@ function serializeTask(task) {
     plan: normalized.plan,
     evidence: normalized.evidence,
     workflow: normalized.workflow,
+    depends_on: normalized.depends_on,
+    files: normalized.files,
     task_number: normalized.task_number
   };
 }
@@ -507,9 +940,11 @@ function getEpicProgress(tasks) {
 function pickEpicFields(epicPayload, fieldNames) {
   const picked = {};
   for (const field of fieldNames) {
-    if (field in epicPayload) {
-      picked[field] = epicPayload[field];
-    }
+    if (!(field in epicPayload)) continue;
+    const value = epicPayload[field];
+    if (value === null || value === '') continue;
+    if (Array.isArray(value) && value.length === 0) continue;
+    picked[field] = value;
   }
   return picked;
 }
@@ -539,7 +974,7 @@ function shapeEpic(epic, tasks = [], options = {}) {
     ...normalized,
     status: deriveEpicStatus(childTasks, normalized),
     progress: getEpicProgress(childTasks),
-    tasks: childTasks.map((task) => shapeTask(task, { view: 'summary' })),
+    tasks: childTasks.map((task) => shapeTask(task, { view: 'summary', allTasks: tasks })),
     adrs: collectEpicAdrs(childTasks)
   };
   const fields = Array.isArray(options.fields) && options.fields.length > 0
@@ -596,7 +1031,7 @@ function nonLiveEpicIdSet(epics, tasks, options = {}) {
 
 function filterTasksForList(tasks, epics, options = {}) {
   // Explicit epic filter (show that epic's tasks) is applied by caller after this.
-  // Default agent list: hide tasks under done/archived epics.
+  // Default agent list: hide tasks under done/archived epics and column=done.
   if (options.include_archived && options.include_done) return tasks;
   // GUI path: hide only archived-epic tasks (done epics still show done cards)
   if (options.live_only === false) {
@@ -606,9 +1041,19 @@ function filterTasksForList(tasks, epics, options = {}) {
     return tasks.filter((task) => !task.epic_id || !archivedIds.has(task.epic_id));
   }
 
-  const hiddenIds = nonLiveEpicIdSet(epics, tasks, options);
-  if (hiddenIds.size === 0) return tasks;
-  return tasks.filter((task) => !task.epic_id || !hiddenIds.has(task.epic_id));
+  const skipDoneOmit = Boolean(options.include_done) || options.col === 'done';
+  const hiddenIds = nonLiveEpicIdSet(
+    epics,
+    tasks,
+    skipDoneOmit ? { ...options, include_done: true } : options
+  );
+  let filtered = hiddenIds.size === 0
+    ? tasks
+    : tasks.filter((task) => !task.epic_id || !hiddenIds.has(task.epic_id));
+  if (!skipDoneOmit) {
+    filtered = filtered.filter((task) => task.column !== 'done');
+  }
+  return filtered;
 }
 
 function getProgress(task) {
@@ -617,6 +1062,105 @@ function getProgress(task) {
   return { done, total };
 }
 
+function currentSubtask(task) {
+  const subtasks = Array.isArray(task && task.subtasks) ? task.subtasks : [];
+  const open = subtasks.find((subtask) => !subtask.done);
+  if (!open) return null;
+  return { id: open.id, text: open.text };
+}
+
+function evidenceProofText(entry) {
+  return normalizeString(entry && entry.summary)
+    || normalizeString(entry && entry.test_command)
+    || normalizeString(entry && entry.diff);
+}
+
+function lastContextResult(task) {
+  const evidence = Array.isArray(task && task.evidence) ? task.evidence : [];
+  for (let i = evidence.length - 1; i >= 0; i--) {
+    const proof = evidenceProofText(evidence[i]);
+    if (proof) return proof;
+  }
+  const notes = normalizeString(task && task.notes);
+  if (notes) return notes;
+  const adr = Array.isArray(task && task.adr) ? task.adr : [];
+  return normalizeString(adr[adr.length - 1] && adr[adr.length - 1].decision);
+}
+
+function compactContextTask(task, allTasks, epicLookup, mode) {
+  const unmet = unmetDependencies(task, allTasks);
+  const subtask = currentSubtask(task);
+  const payload = {
+    mode,
+    next_action: resolveNextAction(task, mode),
+    task_id: task.id,
+    title: task.title,
+    column: task.column,
+    epic_id: task.epic_id,
+    epic_goals: resolveEpicGoals(task, epicLookup),
+    current_subtask: subtask,
+    progress: getProgress(task),
+    files: task.files || [],
+    last_result: lastContextResult(task),
+    blocked: unmet.length > 0,
+    unmet_dependencies: unmet.map((item) => item.id),
+    blocks: computeBlocks(task.id, allTasks)
+  };
+  for (const key of Object.keys(payload)) {
+    const value = payload[key];
+    if (value === null || value === '') delete payload[key];
+    else if (Array.isArray(value) && value.length === 0) delete payload[key];
+  }
+  return payload;
+}
+
+function isUnblockedWork(task, allTasks) {
+  return unmetDependencies(task, allTasks).length === 0;
+}
+
+function isFailedGate(task) {
+  const status = task.workflow && task.workflow.status;
+  return (task.column === 'testing' || task.column === 'review')
+    && (status === 'fail' || status === 'blocked');
+}
+
+function isManualGate(task) {
+  return (task.column === 'testing' || task.column === 'review') && !isFailedGate(task);
+}
+
+async function getContextPayload(options = {}) {
+  const tasks = await allTasks();
+  const epics = await listEpicEntities();
+  const epicLookup = {};
+  for (const epic of epics) {
+    epicLookup[epic.id] = epic;
+  }
+  let liveTasks = filterTasksForList(tasks, epics, {});
+  const epicFilter = options.epic_id || options.epic;
+  if (epicFilter) {
+    liveTasks = liveTasks.filter((task) => taskMatchesEpicFilter(task, epicFilter));
+  }
+  const active = liveTasks.find((task) => task.column === 'active' && isUnblockedWork(task, tasks));
+  if (active) {
+    return compactContextTask(active, tasks, epicLookup, 'continue');
+  }
+  const gateFix = liveTasks.find((task) => isFailedGate(task));
+  if (gateFix) {
+    return compactContextTask(gateFix, tasks, epicLookup, 'continue');
+  }
+  const manualGate = liveTasks.find((task) => isManualGate(task));
+  if (manualGate) {
+    return compactContextTask(manualGate, tasks, epicLookup, 'continue');
+  }
+  const ready = liveTasks
+    .filter((task) => task.column === 'planned' && isUnblockedWork(task, tasks))
+    .sort((a, b) => (a.task_number || 0) - (b.task_number || 0));
+  if (ready.length > 0) {
+    return compactContextTask(ready[0], tasks, epicLookup, 'start');
+  }
+  return { mode: 'idle', next_action: 'idle' };
+}
+
 function resolveEpicGoals(task, epicLookup) {
   if (!task.epic_id) return '';
   if (!epicLookup || typeof epicLookup !== 'object') return '';
@@ -629,17 +1173,14 @@ function pickFields(task, fieldNames) {
   const picked = {};
 
   for (const field of fieldNames) {
-    if (field === 'progress') {
-      picked.progress = getProgress(task);
-      continue;
-    }
-    if (field === 'epic_goals') {
-      picked.epic_goals = task.epic_goals;
-      continue;
-    }
-    if (field in task) {
-      picked[field] = task[field];
-    }
+    let value;
+    if (field === 'progress') value = getProgress(task);
+    else if (field === 'current_subtask') value = currentSubtask(task);
+    else if (field === 'epic_goals') value = task.epic_goals;
+    else if (field in task) value = task[field];
+    else continue;
+    if (value == null || value === '' || (Array.isArray(value) && !value.length)) continue;
+    picked[field] = value;
   }
 
   return picked;
@@ -650,10 +1191,15 @@ function shapeTask(task, options = {}) {
   const fields = Array.isArray(options.fields) && options.fields.length > 0
     ? options.fields
     : (VIEW_FIELDS[options.view || 'full'] || VIEW_FIELDS.full);
+  const allTasks = options.allTasks;
+  const unmet = allTasks ? unmetDependencies(normalized, allTasks) : [];
 
   const withGoals = {
     ...normalized,
-    epic_goals: resolveEpicGoals(normalized, options.epicLookup)
+    epic_goals: resolveEpicGoals(normalized, options.epicLookup),
+    blocked: unmet.length > 0,
+    unmet_dependencies: unmet.map((item) => item.id),
+    blocks: allTasks ? computeBlocks(normalized.id, allTasks) : []
   };
   return pickFields(withGoals, fields);
 }
@@ -684,11 +1230,12 @@ function parseListSection(sectionText) {
 }
 
 async function ensureBacklogDir() {
-  for (const col of COLS) {
-    const colDir = path.join(BACKLOG, col);
+  // Always create the full known set so disabled gates can still hold legacy files until migrated.
+  for (const col of KNOWN_COLS) {
+    const colDir = path.join(backlogDir(), col);
     await fs.mkdir(colDir, { recursive: true });
   }
-  await fs.mkdir(EPICS_DIR, { recursive: true });
+  await fs.mkdir(epicsDir(), { recursive: true });
 }
 
 async function parseMarkdownTask(filePath, column) {
@@ -773,8 +1320,8 @@ async function parseEpic(filePath, column) {
 async function allEpics() {
   const epics = [];
 
-  for (const col of COLS) {
-    const colDir = path.join(BACKLOG, col);
+  for (const col of KNOWN_COLS) {
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       const taskFiles = files
@@ -795,9 +1342,8 @@ async function allEpics() {
         try {
           epics.push(await parseEpic(path.join(colDir, file), col));
         } catch (error) {
-          // File may vanish between readdir and read under concurrent delete.
           if (error.code === 'ENOENT') continue;
-          console.error(`  parse error ${file}: ${error.message}`);
+          throw error;
         }
       }
     } catch (error) {
@@ -813,14 +1359,14 @@ async function allTasks() {
 }
 
 function epicFilePath(epicId) {
-  return path.join(EPICS_DIR, `${epicId}.json`);
+  return path.join(epicsDir(), `${epicId}.json`);
 }
 
 async function nextEpicNumber() {
   await ensureBacklogDir();
   const ids = [];
   try {
-    const files = await fs.readdir(EPICS_DIR);
+    const files = await fs.readdir(epicsDir());
     for (const file of files) {
       if (!isTaskOrEpicDataFile(file)) continue;
       const match = file.match(/^E0*(\d+)\.json$/i);
@@ -870,14 +1416,15 @@ async function listEpicEntities() {
   await ensureBacklogDir();
   const epics = [];
   try {
-    const files = (await fs.readdir(EPICS_DIR))
+    const files = (await fs.readdir(epicsDir()))
       .filter((file) => isTaskOrEpicDataFile(file) && file.endsWith('.json'))
       .sort((left, right) => left.localeCompare(right));
     for (const file of files) {
       try {
-        epics.push(await parseJsonEpic(path.join(EPICS_DIR, file)));
+        epics.push(await parseJsonEpic(path.join(epicsDir(), file)));
       } catch (error) {
-        console.error(`  parse error ${file}: ${error.message}`);
+        if (error.code === 'ENOENT') continue;
+        throw error;
       }
     }
   } catch (error) {
@@ -1036,47 +1583,12 @@ async function updateEpicEntity(epicId, patch) {
     const current = await getEpicEntity(epicId);
     const next = { ...current };
 
-    if (patch.title !== undefined) {
-      const title = normalizeString(patch.title);
-      if (!title) {
-        throw createKanbanError(
-          'VALIDATION_ERROR',
-          'title must be a non-empty string',
-          'Send a non-empty title or omit the field',
-          { field: 'title' },
-          false,
-          400
-        );
-      }
-      next.title = title;
-    }
+    if (patch.title !== undefined) next.title = requireNonEmptyTitle(patch.title);
     if (patch.description !== undefined) next.description = normalizeString(patch.description);
     if (patch.goals !== undefined) next.goals = normalizeString(patch.goals);
-    if (patch.in_scope !== undefined) {
-      if (!Array.isArray(patch.in_scope)) {
-        throw createKanbanError(
-          'VALIDATION_ERROR',
-          'in_scope must be an array of strings',
-          'Send in_scope as an array',
-          { field: 'in_scope' },
-          false,
-          400
-        );
-      }
-      next.in_scope = normalizeStringArray(patch.in_scope);
-    }
+    if (patch.in_scope !== undefined) next.in_scope = requireStringArray(patch.in_scope, 'in_scope');
     if (patch.out_of_scope !== undefined) {
-      if (!Array.isArray(patch.out_of_scope)) {
-        throw createKanbanError(
-          'VALIDATION_ERROR',
-          'out_of_scope must be an array of strings',
-          'Send out_of_scope as an array',
-          { field: 'out_of_scope' },
-          false,
-          400
-        );
-      }
-      next.out_of_scope = normalizeStringArray(patch.out_of_scope);
+      next.out_of_scope = requireStringArray(patch.out_of_scope, 'out_of_scope');
     }
     if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
     if (patch.archived !== undefined) next.archived = Boolean(patch.archived);
@@ -1123,7 +1635,7 @@ async function deleteTaskRecord(taskId) {
   await fs.unlink(filePath).catch((error) => {
     if (error.code !== 'ENOENT') throw error;
   });
-  await removeOtherTaskCopies(task.id, path.join(BACKLOG, '__none__', `${task.id}.json`));
+  await removeOtherTaskCopies(task.id, path.join(backlogDir(), '__none__', `${task.id}.json`));
 
   return {
     ok: true,
@@ -1232,8 +1744,8 @@ function taskMatchesEpicFilter(task, epicFilter) {
 }
 
 async function findFile(epicId) {
-  for (const col of COLS) {
-    const colDir = path.join(BACKLOG, col);
+  for (const col of KNOWN_COLS) {
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       const candidates = files
@@ -1250,22 +1762,30 @@ async function findFile(epicId) {
   return null;
 }
 
+function taskNotFound(taskId) {
+  return createKanbanError(
+    'TASK_NOT_FOUND',
+    `Task ${taskId} was not found`,
+    'Call kanban_read with operation=list to discover valid task ids',
+    { task_id: taskId },
+    false,
+    404
+  );
+}
+
 async function getTask(taskId) {
   const resolvedId = await resolveTaskId(taskId);
-  const filePath = await findFile(resolvedId);
-  if (!filePath) {
-    throw createKanbanError(
-      'TASK_NOT_FOUND',
-      `Task ${taskId} was not found`,
-      'Call kanban_read with operation=list to discover valid task ids',
-      { task_id: taskId },
-      false,
-      404
-    );
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const filePath = await findFile(resolvedId);
+    if (!filePath) throw taskNotFound(taskId);
+    try {
+      return await parseEpic(filePath, path.basename(path.dirname(filePath)));
+    } catch (error) {
+      // Relocate between readdir and read (workflow move).
+      if (error.code !== 'ENOENT' || attempt === 2) throw error;
+    }
   }
-
-  const column = path.basename(path.dirname(filePath));
-  return parseEpic(filePath, column);
+  throw taskNotFound(taskId);
 }
 
 async function resolveTaskId(input) {
@@ -1277,8 +1797,8 @@ async function resolveTaskId(input) {
   const num = parseInt(String(input), 10);
   if (!Number.isFinite(num)) return null;
 
-  for (const col of COLS) {
-    const colDir = path.join(BACKLOG, col);
+  for (const col of KNOWN_COLS) {
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       const rawPattern = new RegExp(`^(?:[A-Z]+-)?${String(num)}(?:-|$)`);
@@ -1298,8 +1818,8 @@ async function resolveTaskId(input) {
 
 async function removeOtherTaskCopies(taskId, keepPath) {
   const keep = path.resolve(keepPath);
-  for (const col of COLS) {
-    const colDir = path.join(BACKLOG, col);
+  for (const col of KNOWN_COLS) {
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       for (const file of files) {
@@ -1321,7 +1841,7 @@ async function writeTask(task, previousFilePath = null, { exclusive = false } =
   const normalized = normalizeTask(task);
   await ensureBacklogDir();
 
-  const nextFilePath = path.join(BACKLOG, normalized.column, `${normalized.id}.json`);
+  const nextFilePath = path.join(backlogDir(), normalized.column, `${normalized.id}.json`);
   const payload = JSON.stringify(serializeTask(normalized), null, 2) + '\n';
   await writeFileAtomic(nextFilePath, payload, { exclusive });
 
@@ -1341,8 +1861,8 @@ async function migrateAll(options = {}) {
   const migrated = [];
   const errors = [];
 
-  for (const col of COLS) {
-    const colDir = path.join(BACKLOG, col);
+  for (const col of KNOWN_COLS) {
+    const colDir = path.join(backlogDir(), col);
     let files;
     try {
       files = await fs.readdir(colDir);
@@ -1387,8 +1907,8 @@ async function migrateAll(options = {}) {
 async function nextTaskNumber() {
   const ids = [];
 
-  for (const col of COLS) {
-    const colDir = path.join(BACKLOG, col);
+  for (const col of KNOWN_COLS) {
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       for (const file of files) {
@@ -1421,6 +1941,71 @@ function allowedColumnsFrom(fromColumn) {
   return COLUMN_TRANSITIONS[fromColumn] ? COLUMN_TRANSITIONS[fromColumn].slice() : [];
 }
 
+/** List tasks sitting in a known physical column dir (even if that column is disabled). */
+async function listTasksInKnownColumn(column) {
+  if (!KNOWN_COLS.includes(column)) {
+    throw createKanbanError(
+      'INVALID_COLUMN',
+      `Column ${column} is not valid`,
+      `Use one of: ${KNOWN_COLS.join(', ')}`,
+      { column, valid_columns: KNOWN_COLS },
+      false,
+      400
+    );
+  }
+  const colDir = path.join(backlogDir(), column);
+  const tasks = [];
+  try {
+    const files = await fs.readdir(colDir);
+    for (const file of files) {
+      if (!isTaskOrEpicDataFile(file)) continue;
+      try {
+        tasks.push(await parseEpic(path.join(colDir, file), column));
+      } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        throw error;
+      }
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return tasks;
+}
+
+/**
+ * Force-move a task to a column without transition checks (config migration only).
+ * Still validates target is a known column and uses writeTask + board lock.
+ */
+async function relocateTask(taskId, targetColumn) {
+  if (!KNOWN_COLS.includes(targetColumn)) {
+    throw createKanbanError(
+      'INVALID_COLUMN',
+      `Column ${targetColumn} is not valid`,
+      `Use one of: ${KNOWN_COLS.join(', ')}`,
+      { column: targetColumn, valid_columns: KNOWN_COLS },
+      false,
+      400
+    );
+  }
+  return withBoardLock(async () => {
+    const resolvedId = await resolveTaskId(taskId);
+    const previousFilePath = await findFile(resolvedId);
+    if (!previousFilePath) {
+      throw createKanbanError(
+        'TASK_NOT_FOUND',
+        `Task ${taskId} was not found`,
+        'Call kanban_read with operation=list to discover valid task ids',
+        { task_id: taskId },
+        false,
+        404
+      );
+    }
+    const current = await parseEpic(previousFilePath, path.basename(path.dirname(previousFilePath)));
+    if (current.column === targetColumn) return current;
+    return writeTask({ ...current, column: targetColumn }, previousFilePath);
+  });
+}
+
 function validateTransition(fromColumn, toColumn, taskId) {
   if (fromColumn === toColumn) return;
   validateColumn(toColumn);
@@ -1497,8 +2082,15 @@ async function doCreate(title, column = 'planned', epicRef = '—', extra = {})
         notes: extra.notes,
         plan: extra.plan,
         adr: extra.adr,
-        evidence: extra.evidence
+        evidence: extra.evidence,
+        depends_on: extra.depends_on,
+        files: extra.files
       });
+      const existing = await allTasks();
+      assertNoDependencyCycle(task.id, normalizeDependsOn(extra.depends_on), existing);
+      if (isWorkColumn(task.column)) {
+        assertUnblockedForColumn(task, task.column, existing);
+      }
       try {
         return await writeTask(task, null, { exclusive: true });
       } catch (error) {
@@ -1516,174 +2108,189 @@ async function doCreate(title, column = 'planned', epicRef = '—', extra = {})
   });
 }
 
-async function updateTaskRecord(taskId, patch) {
-  const resolvedId = await resolveTaskId(taskId);
-  const previousFilePath = await findFile(resolvedId);
-  if (!previousFilePath) {
-    throw createKanbanError(
-      'TASK_NOT_FOUND',
-      `Task ${taskId} was not found`,
-      'Call kanban_read with operation=list to discover valid task ids',
-      { task_id: taskId },
-      false,
-      404
-    );
+function applyColumnPatch(next, current, column) {
+  validateColumn(column);
+  if (column !== current.column) {
+    validateTransition(current.column, column, current.id);
   }
+  next.column = column;
+}
 
-  const current = await parseEpic(previousFilePath, path.basename(path.dirname(previousFilePath)));
-  const next = { ...current };
-
-  if (patch.column !== undefined) {
-    validateColumn(patch.column);
-    if (patch.column !== current.column) {
-      validateTransition(current.column, patch.column, current.id);
-    }
-    next.column = patch.column;
-  }
-  if (patch.title !== undefined) {
-    const title = normalizeString(patch.title);
-    if (!title) {
-      throw createKanbanError(
-        'VALIDATION_ERROR',
-        'title must be a non-empty string',
-        'Send a non-empty title or omit the field',
-        { field: 'title' },
-        false,
-        400
-      );
-    }
-    next.title = title;
-  }
-  if (!patch._skipEpicResolve) {
-    if (patch.epic_id !== undefined || patch.epic !== undefined || patch.epic_group !== undefined) {
-      const ref = patch.epic_id !== undefined
-        ? patch.epic_id
-        : (patch.epic !== undefined ? patch.epic : patch.epic_group);
-      if (isBlankEpicRef(ref)) {
-        next.epic_id = null;
-        next.epic_group = '—';
-      } else {
-        const link = await resolveEpicRef(ref, {
-          createIfMissing: Boolean(
-            patch.epic_group !== undefined && patch.epic_id === undefined && patch.epic === undefined
-          ),
-          skipLock: true
-        });
-        next.epic_id = link.epic_id;
-        next.epic_group = link.epic_group;
-      }
-    }
-  } else {
+async function applyEpicPatch(next, patch) {
+  if (patch._skipEpicResolve) {
     if (patch.epic_id !== undefined) next.epic_id = normalizeEpicId(patch.epic_id);
     if (patch.epic_group !== undefined) next.epic_group = normalizeString(patch.epic_group, '—') || '—';
+    return;
   }
-  if (patch.description !== undefined) next.description = normalizeString(patch.description);
-  if (patch.specs !== undefined) next.specs = normalizeString(patch.specs);
-  if (patch.in_scope !== undefined) {
-    if (!Array.isArray(patch.in_scope)) {
+  if (patch.epic_id === undefined && patch.epic === undefined && patch.epic_group === undefined) {
+    return;
+  }
+  const ref = patch.epic_id !== undefined
+    ? patch.epic_id
+    : (patch.epic !== undefined ? patch.epic : patch.epic_group);
+  if (isBlankEpicRef(ref)) {
+    next.epic_id = null;
+    next.epic_group = '—';
+    return;
+  }
+  const link = await resolveEpicRef(ref, {
+    createIfMissing: Boolean(
+      patch.epic_group !== undefined && patch.epic_id === undefined && patch.epic === undefined
+    ),
+    skipLock: true
+  });
+  next.epic_id = link.epic_id;
+  next.epic_group = link.epic_group;
+}
+
+function applyEvidencePatch(next, patch) {
+  if (patch.appendEvidence !== undefined) {
+    if (!patch.appendEvidence || typeof patch.appendEvidence !== 'object' || Array.isArray(patch.appendEvidence)) {
       throw createKanbanError(
         'VALIDATION_ERROR',
-        'in_scope must be an array of strings',
-        'Send in_scope as an array',
-        { field: 'in_scope' },
+        'appendEvidence must be an evidence object',
+        'Send a single evidence entry to append',
+        { field: 'appendEvidence' },
         false,
         400
       );
     }
-    next.in_scope = patch.in_scope;
+    next.evidence = [...normalizeEvidence(next.evidence), ...normalizeEvidence([patch.appendEvidence])];
+  }
+  if (patch.evidence !== undefined) {
+    assertIsArray(
+      patch.evidence,
+      'evidence',
+      'evidence must be an array',
+      'Send evidence as an array of evidence objects'
+    );
+    next.evidence = patch.evidence;
+  }
+}
+
+function applyMarkSubtaskDone(next, taskId, rawIndex) {
+  const index = rawIndex === undefined || rawIndex === null
+    ? next.subtasks.findIndex((subtask) => !subtask.done)
+    : Number(rawIndex);
+  if (!Number.isInteger(index) || index < 0 || index >= next.subtasks.length) {
+    throw createKanbanError(
+      'INVALID_SUBTASK_INDEX',
+      'No valid plan step was provided',
+      'Provide the zero-based index of an incomplete subtask',
+      { index, total_subtasks: next.subtasks.length, task_id: taskId },
+      false,
+      400
+    );
+  }
+  next.subtasks = next.subtasks.map((subtask, subtaskIndex) => ({
+    ...subtask,
+    done: subtaskIndex === index ? true : subtask.done
+  }));
+}
+
+function applySubtaskProgressPatch(next, patch, taskId) {
+  if (Object.prototype.hasOwnProperty.call(patch, 'mark_subtask_done')) {
+    applyMarkSubtaskDone(next, taskId, patch.mark_subtask_done);
+  }
+}
+
+function applyScalarTaskPatch(next, patch) {
+  if (patch.depends_on !== undefined) {
+    assertIsArray(
+      patch.depends_on,
+      'depends_on',
+      'depends_on must be an array of task ids',
+      'Send depends_on as an array like ["001"]'
+    );
+    next.depends_on = patch.depends_on;
+  }
+  if (patch.files !== undefined) {
+    assertIsArray(
+      patch.files,
+      'files',
+      'files must be an array of paths',
+      'Send files as an array like ["src/foo.js"]'
+    );
+    next.files = patch.files;
   }
+  if (patch.title !== undefined) next.title = requireNonEmptyTitle(patch.title);
+  if (patch.description !== undefined) next.description = normalizeString(patch.description);
+  if (patch.specs !== undefined) next.specs = normalizeString(patch.specs);
+  if (patch.in_scope !== undefined) next.in_scope = requireStringArray(patch.in_scope, 'in_scope');
   if (patch.out_of_scope !== undefined) {
-    if (!Array.isArray(patch.out_of_scope)) {
-      throw createKanbanError(
-        'VALIDATION_ERROR',
-        'out_of_scope must be an array of strings',
-        'Send out_of_scope as an array',
-        { field: 'out_of_scope' },
-        false,
-        400
-      );
-    }
-    next.out_of_scope = patch.out_of_scope;
+    next.out_of_scope = requireStringArray(patch.out_of_scope, 'out_of_scope');
   }
   if (patch.acceptance_criteria !== undefined) {
-    if (!Array.isArray(patch.acceptance_criteria)) {
-      throw createKanbanError(
-        'VALIDATION_ERROR',
-        'acceptance_criteria must be an array of strings',
-        'Send acceptance_criteria as an array',
-        { field: 'acceptance_criteria' },
-        false,
-        400
-      );
-    }
-    next.acceptance_criteria = patch.acceptance_criteria;
-  }
-  if (patch.test_cases !== undefined) {
-    if (!Array.isArray(patch.test_cases)) {
-      throw createKanbanError(
-        'VALIDATION_ERROR',
-        'test_cases must be an array of strings',
-        'Send test_cases as an array',
-        { field: 'test_cases' },
-        false,
-        400
-      );
-    }
-    next.test_cases = patch.test_cases;
+    next.acceptance_criteria = requireStringArray(patch.acceptance_criteria, 'acceptance_criteria');
   }
+  if (patch.test_cases !== undefined) next.test_cases = requireStringArray(patch.test_cases, 'test_cases');
   if (patch.subtasks !== undefined) {
-    if (!Array.isArray(patch.subtasks)) {
-      throw createKanbanError(
-        'VALIDATION_ERROR',
-        'subtasks must be an array',
-        'Send subtasks as an array of objects',
-        { field: 'subtasks' },
-        false,
-        400
-      );
-    }
+    assertIsArray(
+      patch.subtasks,
+      'subtasks',
+      'subtasks must be an array',
+      'Send subtasks as an array of objects'
+    );
     next.subtasks = patch.subtasks;
   }
-  if (patch.adr !== undefined) {
-    if (Array.isArray(patch.adr)) {
-      next.adr = normalizeAdr(patch.adr);
-    } else {
-      next.adr = appendAdrEntry(next.adr, patch.adr);
-    }
-  }
+  if (patch.adr !== undefined) next.adr = applyAdrPatch(next.adr, patch.adr);
   if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
   if (patch.plan !== undefined) next.plan = patch.plan;
   if (patch.workflow !== undefined) {
     next.workflow = patch.workflow === null ? null : normalizeWorkflow(patch.workflow);
   }
-  if (patch.appendEvidence !== undefined) {
-    if (!patch.appendEvidence || typeof patch.appendEvidence !== 'object' || Array.isArray(patch.appendEvidence)) {
-      throw createKanbanError(
-        'VALIDATION_ERROR',
-        'appendEvidence must be an evidence object',
-        'Send a single evidence entry to append',
-        { field: 'appendEvidence' },
-        false,
-        400
-      );
-    }
-    next.evidence = [...normalizeEvidence(next.evidence), ...normalizeEvidence([patch.appendEvidence])];
+}
+
+async function assertTaskPatchInvariants(current, next, patch) {
+  const columnChanged = next.column !== current.column;
+  const depsChanged = patch.depends_on !== undefined;
+  const enteringDone = columnChanged && next.column === 'done';
+  let others = null;
+  if (depsChanged || (columnChanged && isWorkColumn(next.column)) || enteringDone) {
+    others = await allTasks();
   }
-  if (patch.evidence !== undefined) {
-    if (!Array.isArray(patch.evidence)) {
-      throw createKanbanError(
-        'VALIDATION_ERROR',
-        'evidence must be an array',
-        'Send evidence as an array of evidence objects',
-        { field: 'evidence' },
-        false,
-        400
-      );
-    }
-    next.evidence = patch.evidence;
+  if (depsChanged) {
+    assertNoDependencyCycle(current.id, normalizeDependsOn(next.depends_on), others);
+  }
+  if (columnChanged && isWorkColumn(next.column)) {
+    assertUnblockedForColumn(normalizeTask(next), next.column, others);
   }
+  if (columnChanged) {
+    assertEvidenceForGate(current, next);
+  }
+  return { enteringDone, others };
+}
 
-  return writeTask(next, previousFilePath);
+async function updateTaskRecord(taskId, patch) {
+  const resolvedId = await resolveTaskId(taskId);
+  const previousFilePath = await findFile(resolvedId);
+  if (!previousFilePath) {
+    throw createKanbanError(
+      'TASK_NOT_FOUND',
+      `Task ${taskId} was not found`,
+      'Call kanban_read with operation=list to discover valid task ids',
+      { task_id: taskId },
+      false,
+      404
+    );
+  }
+
+  const current = await parseEpic(previousFilePath, path.basename(path.dirname(previousFilePath)));
+  const next = { ...current };
+
+  if (patch.column !== undefined) applyColumnPatch(next, current, patch.column);
+  applyScalarTaskPatch(next, patch);
+  applySubtaskProgressPatch(next, patch, current.id);
+  await applyEpicPatch(next, patch);
+  applyEvidencePatch(next, patch);
+
+  const { enteringDone, others } = await assertTaskPatchInvariants(current, next, patch);
+  const written = await writeTask(next, previousFilePath);
+  if (enteringDone) {
+    const board = others.map((other) => (other.id === written.id ? written : other));
+    written.unblocked_tasks = newlyUnblockedTasks(written.id, board);
+  }
+  return written;
 }
 
 function scheduleWorkflowEnqueue(previousColumn, updated) {
@@ -1723,7 +2330,12 @@ async function doMove(epicId, target) {
     await updateTask(epicId, { column: target });
     return true;
   } catch (error) {
-    if (error.code === 'TASK_NOT_FOUND' || error.code === 'INVALID_COLUMN' || error.code === 'INVALID_TRANSITION') {
+    if (
+      error.code === 'TASK_NOT_FOUND'
+      || error.code === 'INVALID_COLUMN'
+      || error.code === 'INVALID_TRANSITION'
+      || error.code === 'EVIDENCE_REQUIRED'
+    ) {
       return false;
     }
     throw error;
@@ -1808,10 +2420,18 @@ module.exports = {
   missingRecommendedCreateFields,
   missingRecommendedEpicCreateFields,
   getProgress,
+  getContextPayload,
+  unmetDependencies,
+  computeBlocks,
+  newlyUnblockedTasks,
   getEpicProgress,
   deriveEpicStatus,
   resolveTaskId,
+  applyBoardLayout,
+  listTasksInKnownColumn,
+  relocateTask,
   COLS,
+  KNOWN_COLS,
   STATUS_MAP,
   WORKFLOW_STAGES,
   COLUMN_TRANSITIONS,
@@ -1820,9 +2440,18 @@ module.exports = {
   VIEW_FIELDS,
   EPIC_VIEW_FIELDS,
   normalizeEvidence,
+  hasProofEvidence,
+  assertEvidenceForGate,
   normalizeWorkflow,
   LIVE_EPIC_STATUSES,
   RECOMMENDED_CREATE_FIELDS,
   RECOMMENDED_EPIC_CREATE_FIELDS,
-  EPICS_DIR
+  get EPICS_DIR() {
+    return epicsDir();
+  }
 };
+
+// Keep live refs for applyBoardLayout consumers that read module.exports.COLS
+module.exports.COLS = COLS;
+module.exports.COLUMN_TRANSITIONS = COLUMN_TRANSITIONS;
+module.exports.WORKFLOW_STAGES = WORKFLOW_STAGES;