kanbango 3.8.0 → 5.1.0

package/kanban.js

@@ -1,8 +1,17 @@
 const fs = require('fs').promises;
 const path = require('path');
 
-const BACKLOG = path.join(process.cwd(), 'backlog');
-const EPICS_DIR = path.join(BACKLOG, 'epics');
+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. */
@@ -52,7 +61,7 @@ function applyBoardLayout({ cols, transitions, workflowStages } = {}) {
   module.exports.WORKFLOW_STAGES = WORKFLOW_STAGES;
 }
 const VIEW_FIELDS = {
-  summary: ['task_number', 'title', 'column', 'epic_id', 'epic_group', 'created', 'progress', 'blocked'],
+  summary: ['id', 'task_number', 'title', 'column', 'epic_id', 'progress', 'blocked'],
   planning: [
     'task_number',
     'title',
@@ -74,30 +83,17 @@ const VIEW_FIELDS = {
     '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',
-    'depends_on',
     'files',
-    'blocked',
-    'unmet_dependencies',
-    'blocks'
+    'blocked'
   ],
   full: [
     'task_number',
@@ -189,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;
 }
@@ -225,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];
 }
@@ -249,6 +366,48 @@ 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 '';
@@ -390,6 +549,68 @@ function firstEnabledGateColumn() {
   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';
@@ -408,8 +629,7 @@ function resolveNextAction(task, mode) {
     return 'fix_gate';
   }
   if (currentSubtask(task)) return 'advance';
-  const evidence = Array.isArray(task.evidence) ? task.evidence : [];
-  if (evidence.length === 0) return 'evidence';
+  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';
@@ -720,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;
 }
@@ -809,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) {
@@ -819,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) {
@@ -837,10 +1069,28 @@ function currentSubtask(task) {
   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);
-  return {
+  const payload = {
     mode,
     next_action: resolveNextAction(task, mode),
     task_id: task.id,
@@ -851,10 +1101,31 @@ function compactContextTask(task, allTasks, epicLookup, mode) {
     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 = {}) {
@@ -869,20 +1140,20 @@ async function getContextPayload(options = {}) {
   if (epicFilter) {
     liveTasks = liveTasks.filter((task) => taskMatchesEpicFilter(task, epicFilter));
   }
-  const active = liveTasks.find((task) => task.column === 'active');
+  const active = liveTasks.find((task) => task.column === 'active' && isUnblockedWork(task, tasks));
   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');
-  });
+  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' && unmetDependencies(task, tasks).length === 0)
+    .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');
@@ -902,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;
@@ -964,10 +1232,10 @@ function parseListSection(sectionText) {
 async function ensureBacklogDir() {
   // 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);
+    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) {
@@ -1053,7 +1321,7 @@ async function allEpics() {
   const epics = [];
 
   for (const col of KNOWN_COLS) {
-    const colDir = path.join(BACKLOG, col);
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       const taskFiles = files
@@ -1074,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) {
@@ -1092,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);
@@ -1149,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) {
@@ -1315,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);
@@ -1402,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,
@@ -1512,7 +1745,7 @@ function taskMatchesEpicFilter(task, epicFilter) {
 
 async function findFile(epicId) {
   for (const col of KNOWN_COLS) {
-    const colDir = path.join(BACKLOG, col);
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       const candidates = files
@@ -1529,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) {
@@ -1557,7 +1798,7 @@ async function resolveTaskId(input) {
   if (!Number.isFinite(num)) return null;
 
   for (const col of KNOWN_COLS) {
-    const colDir = path.join(BACKLOG, col);
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       const rawPattern = new RegExp(`^(?:[A-Z]+-)?${String(num)}(?:-|$)`);
@@ -1578,7 +1819,7 @@ async function resolveTaskId(input) {
 async function removeOtherTaskCopies(taskId, keepPath) {
   const keep = path.resolve(keepPath);
   for (const col of KNOWN_COLS) {
-    const colDir = path.join(BACKLOG, col);
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       for (const file of files) {
@@ -1600,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 });
 
@@ -1621,7 +1862,7 @@ async function migrateAll(options = {}) {
   const errors = [];
 
   for (const col of KNOWN_COLS) {
-    const colDir = path.join(BACKLOG, col);
+    const colDir = path.join(backlogDir(), col);
     let files;
     try {
       files = await fs.readdir(colDir);
@@ -1667,7 +1908,7 @@ async function nextTaskNumber() {
   const ids = [];
 
   for (const col of KNOWN_COLS) {
-    const colDir = path.join(BACKLOG, col);
+    const colDir = path.join(backlogDir(), col);
     try {
       const files = await fs.readdir(colDir);
       for (const file of files) {
@@ -1712,7 +1953,7 @@ async function listTasksInKnownColumn(column) {
       400
     );
   }
-  const colDir = path.join(BACKLOG, column);
+  const colDir = path.join(backlogDir(), column);
   const tasks = [];
   try {
     const files = await fs.readdir(colDir);
@@ -1867,199 +2108,140 @@ 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;
+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.depends_on !== undefined) {
-    if (!Array.isArray(patch.depends_on)) {
+  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',
-        'depends_on must be an array of task ids',
-        'Send depends_on as an array like ["001"]',
-        { field: 'depends_on' },
+        '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) {
+    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) {
-    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
-      );
-    }
+    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) {
-    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 {
-    if (patch.epic_id !== undefined) next.epic_id = normalizeEpicId(patch.epic_id);
-    if (patch.epic_group !== undefined) next.epic_group = normalizeString(patch.epic_group, '—') || '—';
-  }
+  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) {
-    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 = 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 = 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])];
-  }
-  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;
-  }
+}
 
+async function assertTaskPatchInvariants(current, next, patch) {
   const columnChanged = next.column !== current.column;
   const depsChanged = patch.depends_on !== undefined;
   const enteringDone = columnChanged && next.column === 'done';
@@ -2073,7 +2255,36 @@ async function updateTaskRecord(taskId, patch) {
   if (columnChanged && isWorkColumn(next.column)) {
     assertUnblockedForColumn(normalizeTask(next), next.column, others);
   }
+  if (columnChanged) {
+    assertEvidenceForGate(current, next);
+  }
+  return { enteringDone, others };
+}
+
+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));
@@ -2119,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;
@@ -2224,11 +2440,15 @@ 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