kanbango 3.5.0 → 3.8.0

package/kanban.js

@@ -3,15 +3,56 @@ const path = require('path');
 
 const BACKLOG = path.join(process.cwd(), 'backlog');
 const EPICS_DIR = path.join(BACKLOG, 'epics');
-const COLS = ['active', 'planned', 'icebox', 'done'];
+/** 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',
   icebox: 'icebox',
+  testing: 'testing',
+  review: 'review',
   done: 'done'
 };
+/** 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. Mutated by applyBoardLayout.
+let COLUMN_TRANSITIONS = {
+  icebox: ['planned'],
+  planned: ['active', 'icebox', 'testing'],
+  active: ['planned', 'testing', 'icebox'],
+  testing: ['active', 'review'],
+  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: ['task_number', 'title', 'column', 'epic_id', 'epic_group', 'created', 'progress', 'blocked'],
   planning: [
     'task_number',
     'title',
@@ -26,7 +67,11 @@ const VIEW_FIELDS = {
     'in_scope',
     'out_of_scope',
     'acceptance_criteria',
-    'test_cases'
+    'test_cases',
+    'depends_on',
+    'blocked',
+    'unmet_dependencies',
+    'blocks'
   ],
   execution: [
     'task_number',
@@ -44,7 +89,15 @@ const VIEW_FIELDS = {
     'acceptance_criteria',
     'test_cases',
     'subtasks',
-    'adr'
+    'adr',
+    'evidence',
+    'plan',
+    'workflow',
+    'depends_on',
+    'files',
+    'blocked',
+    'unmet_dependencies',
+    'blocks'
   ],
   full: [
     'task_number',
@@ -63,7 +116,15 @@ const VIEW_FIELDS = {
     'test_cases',
     'subtasks',
     'adr',
-    'notes'
+    'notes',
+    'evidence',
+    'plan',
+    'workflow',
+    'depends_on',
+    'files',
+    'blocked',
+    'unmet_dependencies',
+    'blocks'
   ]
 };
 
@@ -188,6 +249,173 @@ function normalizeStringArray(value) {
     .filter(Boolean);
 }
 
+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 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';
+  const evidence = Array.isArray(task.evidence) ? task.evidence : [];
+  if (evidence.length === 0) 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'
@@ -261,14 +489,39 @@ function normalizeSubtasks(value) {
 
 function normalizeEvidence(value) {
   if (!Array.isArray(value)) return [];
-  return value.map((item) => ({
-    diff: normalizeString(item && item.diff),
-    test_command: normalizeString(item && item.test_command),
-    stdout: normalizeString(item && item.stdout),
-    stderr: normalizeString(item && item.stderr),
-    exit_code: Number.isInteger(item && item.exit_code) ? item.exit_code : null,
-    created: normalizeString(item && item.created) || todayIso()
-  }));
+  return value.map((item) => {
+    const stage = normalizeString(item && item.stage);
+    const verdict = normalizeString(item && item.verdict);
+    return {
+      diff: normalizeString(item && item.diff),
+      test_command: normalizeString(item && item.test_command),
+      stdout: normalizeString(item && item.stdout),
+      stderr: normalizeString(item && item.stderr),
+      exit_code: Number.isInteger(item && item.exit_code) ? item.exit_code : null,
+      created: normalizeString(item && item.created) || todayIso(),
+      stage: WORKFLOW_STAGES.includes(stage) || stage === 'plan' ? stage : '',
+      agent: normalizeString(item && item.agent),
+      verdict: EVIDENCE_VERDICTS.includes(verdict) ? verdict : '',
+      summary: normalizeString(item && item.summary)
+    };
+  });
+}
+
+function normalizeWorkflow(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const stage = normalizeString(value.stage);
+  const status = normalizeString(value.status);
+  const agent = normalizeString(value.agent);
+  const runId = normalizeString(value.run_id);
+  if (!stage && !status && !agent && !runId) return null;
+  return {
+    stage: WORKFLOW_STAGES.includes(stage) ? stage : null,
+    status: WORKFLOW_STATUSES.includes(status) ? status : 'idle',
+    agent,
+    run_id: runId,
+    started_at: normalizeString(value.started_at) || undefined,
+    finished_at: normalizeString(value.finished_at) || undefined
+  };
 }
 
 function normalizeAdr(value) {
@@ -340,7 +593,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(),
@@ -355,6 +609,9 @@ function normalizeTask(task) {
     notes: normalizeString(task.notes),
     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)
   };
 
@@ -381,6 +638,9 @@ function serializeTask(task) {
     notes: normalized.notes,
     plan: normalized.plan,
     evidence: normalized.evidence,
+    workflow: normalized.workflow,
+    depends_on: normalized.depends_on,
+    files: normalized.files,
     task_number: normalized.task_number
   };
 }
@@ -418,7 +678,9 @@ function serializeEpic(epic) {
 function deriveEpicStatus(tasks, epic) {
   if (epic && epic.archived) return 'archived';
   if (!tasks || tasks.length === 0) return 'empty';
-  if (tasks.some((task) => task.column === 'active')) return 'active';
+  if (tasks.some((task) => WORKFLOW_STAGES.includes(task.column) || task.column === 'active')) {
+    return 'active';
+  }
   if (tasks.every((task) => task.column === 'done')) return 'done';
   return 'planned';
 }
@@ -436,13 +698,21 @@ function getEpicProgress(tasks) {
     tasks_done: 0,
     tasks_active: 0,
     tasks_planned: 0,
-    tasks_icebox: 0
+    tasks_icebox: 0,
+    tasks_testing: 0,
+    tasks_review: 0
+  };
+  const keyByCol = {
+    done: 'tasks_done',
+    active: 'tasks_active',
+    planned: 'tasks_planned',
+    icebox: 'tasks_icebox',
+    testing: 'tasks_testing',
+    review: 'tasks_review'
   };
   for (const task of tasks) {
-    if (task.column === 'done') progress.tasks_done += 1;
-    else if (task.column === 'active') progress.tasks_active += 1;
-    else if (task.column === 'planned') progress.tasks_planned += 1;
-    else if (task.column === 'icebox') progress.tasks_icebox += 1;
+    const key = keyByCol[task.column];
+    if (key) progress[key] += 1;
   }
   return progress;
 }
@@ -482,7 +752,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
@@ -560,6 +830,66 @@ 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 compactContextTask(task, allTasks, epicLookup, mode) {
+  const unmet = unmetDependencies(task, allTasks);
+  const subtask = currentSubtask(task);
+  return {
+    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 || [],
+    blocked: unmet.length > 0,
+    unmet_dependencies: unmet.map((item) => item.id),
+    blocks: computeBlocks(task.id, allTasks)
+  };
+}
+
+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');
+  if (active) {
+    return compactContextTask(active, tasks, epicLookup, 'continue');
+  }
+  const gateFix = liveTasks.find((task) => {
+    const status = task.workflow && task.workflow.status;
+    return (task.column === 'testing' || task.column === 'review')
+      && (status === 'fail' || status === 'blocked');
+  });
+  if (gateFix) {
+    return compactContextTask(gateFix, tasks, epicLookup, 'continue');
+  }
+  const ready = liveTasks
+    .filter((task) => task.column === 'planned' && unmetDependencies(task, tasks).length === 0)
+    .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 '';
@@ -593,10 +923,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);
 }
@@ -627,7 +962,8 @@ function parseListSection(sectionText) {
 }
 
 async function ensureBacklogDir() {
-  for (const col of COLS) {
+  // 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(BACKLOG, col);
     await fs.mkdir(colDir, { recursive: true });
   }
@@ -716,7 +1052,7 @@ async function parseEpic(filePath, column) {
 async function allEpics() {
   const epics = [];
 
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1175,7 +1511,7 @@ function taskMatchesEpicFilter(task, epicFilter) {
 }
 
 async function findFile(epicId) {
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1220,7 +1556,7 @@ async function resolveTaskId(input) {
   const num = parseInt(String(input), 10);
   if (!Number.isFinite(num)) return null;
 
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1241,7 +1577,7 @@ async function resolveTaskId(input) {
 
 async function removeOtherTaskCopies(taskId, keepPath) {
   const keep = path.resolve(keepPath);
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1284,7 +1620,7 @@ async function migrateAll(options = {}) {
   const migrated = [];
   const errors = [];
 
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     let files;
     try {
@@ -1330,7 +1666,7 @@ async function migrateAll(options = {}) {
 async function nextTaskNumber() {
   const ids = [];
 
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1360,6 +1696,97 @@ function validateColumn(column, fieldName = 'column') {
   }
 }
 
+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(BACKLOG, 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);
+  const allowed = allowedColumnsFrom(fromColumn);
+  if (allowed.includes(toColumn)) return;
+  throw createKanbanError(
+    'INVALID_TRANSITION',
+    taskId
+      ? `Cannot move task ${taskId} from ${fromColumn} to ${toColumn}`
+      : `Cannot move from ${fromColumn} to ${toColumn}`,
+    `From ${fromColumn} you can move only to: ${allowed.join(', ') || '(none)'}`,
+    {
+      task_id: taskId || undefined,
+      from: fromColumn,
+      to: toColumn,
+      allowed_columns: allowed
+    },
+    false,
+    400
+  );
+}
+
 function validatePatch(patch) {
   if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
     throw createKanbanError(
@@ -1413,8 +1840,16 @@ async function doCreate(title, column = 'planned', epicRef = '—', extra = {})
         subtasks: extra.subtasks,
         notes: extra.notes,
         plan: extra.plan,
-        evidence: extra.evidence
+        adr: extra.adr,
+        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) {
@@ -1451,8 +1886,37 @@ async function updateTaskRecord(taskId, patch) {
 
   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.depends_on !== undefined) {
+    if (!Array.isArray(patch.depends_on)) {
+      throw createKanbanError(
+        'VALIDATION_ERROR',
+        'depends_on must be an array of task ids',
+        'Send depends_on as an array like ["001"]',
+        { field: 'depends_on' },
+        false,
+        400
+      );
+    }
+    next.depends_on = patch.depends_on;
+  }
+  if (patch.files !== undefined) {
+    if (!Array.isArray(patch.files)) {
+      throw createKanbanError(
+        'VALIDATION_ERROR',
+        'files must be an array of paths',
+        'Send files as an array like ["src/foo.js"]',
+        { field: 'files' },
+        false,
+        400
+      );
+    }
+    next.files = patch.files;
+  }
   if (patch.title !== undefined) {
     const title = normalizeString(patch.title);
     if (!title) {
@@ -1566,6 +2030,22 @@ async function updateTaskRecord(taskId, patch) {
   }
   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])];
+  }
   if (patch.evidence !== undefined) {
     if (!Array.isArray(patch.evidence)) {
       throw createKanbanError(
@@ -1580,12 +2060,58 @@ async function updateTaskRecord(taskId, patch) {
     next.evidence = patch.evidence;
   }
 
-  return writeTask(next, previousFilePath);
+  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 (depsChanged) {
+    assertNoDependencyCycle(current.id, normalizeDependsOn(next.depends_on), others);
+  }
+  if (columnChanged && isWorkColumn(next.column)) {
+    assertUnblockedForColumn(normalizeTask(next), next.column, others);
+  }
+
+  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) {
+  if (!updated || !WORKFLOW_STAGES.includes(updated.column)) return;
+  if (previousColumn === updated.column) return;
+  // Lazy require avoids circular load: workflow.js requires kanban.js.
+  setImmediate(() => {
+    try {
+      const workflow = require('./workflow.js');
+      Promise.resolve(workflow.maybeEnqueueOnColumnEnter(updated, previousColumn)).catch((err) => {
+        console.error('workflow enqueue failed:', err && err.message ? err.message : err);
+      });
+    } catch (err) {
+      console.error('workflow load failed:', err && err.message ? err.message : err);
+    }
+  });
 }
 
 async function updateTask(taskId, patch) {
   validatePatch(patch);
-  return withBoardLock(() => updateTaskRecord(taskId, patch));
+  let previousColumn = null;
+  const updated = await withBoardLock(async () => {
+    const resolvedId = await resolveTaskId(taskId);
+    const previousFilePath = await findFile(resolvedId);
+    if (previousFilePath) {
+      const current = await parseEpic(previousFilePath, path.basename(path.dirname(previousFilePath)));
+      previousColumn = current.column;
+    }
+    return updateTaskRecord(taskId, patch);
+  });
+  scheduleWorkflowEnqueue(previousColumn, updated);
+  return updated;
 }
 
 async function doMove(epicId, target) {
@@ -1593,7 +2119,7 @@ async function doMove(epicId, target) {
     await updateTask(epicId, { column: target });
     return true;
   } catch (error) {
-    if (error.code === 'TASK_NOT_FOUND' || error.code === 'INVALID_COLUMN') {
+    if (error.code === 'TASK_NOT_FOUND' || error.code === 'INVALID_COLUMN' || error.code === 'INVALID_TRANSITION') {
       return false;
     }
     throw error;
@@ -1678,15 +2204,34 @@ module.exports = {
   missingRecommendedCreateFields,
   missingRecommendedEpicCreateFields,
   getProgress,
+  getContextPayload,
+  unmetDependencies,
+  computeBlocks,
+  newlyUnblockedTasks,
   getEpicProgress,
   deriveEpicStatus,
   resolveTaskId,
+  applyBoardLayout,
+  listTasksInKnownColumn,
+  relocateTask,
   COLS,
+  KNOWN_COLS,
   STATUS_MAP,
+  WORKFLOW_STAGES,
+  COLUMN_TRANSITIONS,
+  allowedColumnsFrom,
+  validateTransition,
   VIEW_FIELDS,
   EPIC_VIEW_FIELDS,
+  normalizeEvidence,
+  normalizeWorkflow,
   LIVE_EPIC_STATUSES,
   RECOMMENDED_CREATE_FIELDS,
   RECOMMENDED_EPIC_CREATE_FIELDS,
   EPICS_DIR
 };
+
+// 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;