kanbango 3.1.0 → 3.3.0

package/kanban.js

@@ -41,7 +41,8 @@ const VIEW_FIELDS = {
     'out_of_scope',
     'acceptance_criteria',
     'test_cases',
-    'subtasks'
+    'subtasks',
+    'comments'
   ],
   full: [
     'task_number',
@@ -58,17 +59,19 @@ const VIEW_FIELDS = {
     'acceptance_criteria',
     'test_cases',
     'subtasks',
-    'notes'
+    'notes',
+    'comments'
   ]
 };
 
 const EPIC_VIEW_FIELDS = {
-  summary: ['id', 'title', 'created', 'status', 'progress'],
+  summary: ['id', 'title', 'created', 'status', 'archived', 'progress'],
   planning: [
     'id',
     'title',
     'created',
     'status',
+    'archived',
     'progress',
     'description',
     'goals',
@@ -80,6 +83,7 @@ const EPIC_VIEW_FIELDS = {
     'title',
     'created',
     'status',
+    'archived',
     'progress',
     'description',
     'goals',
@@ -90,6 +94,8 @@ const EPIC_VIEW_FIELDS = {
   ]
 };
 
+const LIVE_EPIC_STATUSES = ['empty', 'planned', 'active'];
+
 // Hard-required on create: title only (keeps GUI/CLI quick-add usable).
 // Strongly recommended for agent/planned work — missing ones yield warnings, not errors.
 const RECOMMENDED_CREATE_FIELDS = [
@@ -117,6 +123,43 @@ function createKanbanError(code, message, hint, details = {}, retryable = false,
   return error;
 }
 
+// Serialize board mutations so concurrent create/move/update cannot race on ids or paths.
+let mutationTail = Promise.resolve();
+
+function withBoardLock(fn) {
+  const run = mutationTail.then(() => fn());
+  mutationTail = run.then(() => undefined, () => undefined);
+  return run;
+}
+
+function isTaskOrEpicDataFile(file) {
+  if (!file || file.startsWith('.')) return false;
+  return file.endsWith('.json') || file.endsWith('.md');
+}
+
+async function writeFileAtomic(filePath, payload, { exclusive = false } = {}) {
+  const dir = path.dirname(filePath);
+  const base = path.basename(filePath);
+  const tempPath = path.join(
+    dir,
+    `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`
+  );
+
+  await fs.writeFile(tempPath, payload, 'utf-8');
+  try {
+    if (exclusive) {
+      // Atomic create-if-absent: never exposes an empty final path to readers.
+      await fs.link(tempPath, filePath);
+      await fs.unlink(tempPath).catch(() => undefined);
+    } else {
+      await fs.rename(tempPath, filePath);
+    }
+  } catch (error) {
+    await fs.unlink(tempPath).catch(() => undefined);
+    throw error;
+  }
+}
+
 function todayIso() {
   return new Date().toISOString().split('T')[0];
 }
@@ -212,6 +255,28 @@ function normalizeSubtasks(value) {
   })).filter((subtask) => subtask.text);
 }
 
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function nextCommentId(comments) {
+  const max = comments.reduce((highest, comment) => {
+    const match = String(comment && comment.id || '').match(/^c-(\d+)$/i);
+    return match ? Math.max(highest, parseInt(match[1], 10)) : highest;
+  }, 0);
+  return `c-${max + 1}`;
+}
+
+function normalizeComments(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item, idx) => ({
+    id: normalizeString(item && item.id, `c-${idx + 1}`),
+    created: normalizeString(item && item.created) || nowIso(),
+    author: normalizeString(item && item.author, 'user') || 'user',
+    text: normalizeString(item && item.text)
+  })).filter((item) => item.text);
+}
+
 function normalizeEvidence(value) {
   if (!Array.isArray(value)) return [];
   return value.map((item) => ({
@@ -251,6 +316,7 @@ function normalizeTask(task) {
     test_cases: normalizeStringArray(task.test_cases),
     subtasks: normalizeSubtasks(task.subtasks),
     notes: normalizeString(task.notes),
+    comments: normalizeComments(task.comments),
     plan: normalizePlan(task.plan),
     evidence: normalizeEvidence(task.evidence),
     task_number: extractTaskNumber(id)
@@ -276,6 +342,7 @@ function serializeTask(task) {
     test_cases: normalized.test_cases,
     subtasks: normalized.subtasks,
     notes: normalized.notes,
+    comments: normalized.comments,
     plan: normalized.plan,
     evidence: normalized.evidence,
     task_number: normalized.task_number
@@ -292,7 +359,8 @@ function normalizeEpic(epic) {
     goals: normalizeString(epic && epic.goals),
     in_scope: normalizeStringArray(epic && epic.in_scope),
     out_of_scope: normalizeStringArray(epic && epic.out_of_scope),
-    notes: normalizeString(epic && epic.notes)
+    notes: normalizeString(epic && epic.notes),
+    archived: Boolean(epic && epic.archived)
   };
 }
 
@@ -306,17 +374,26 @@ function serializeEpic(epic) {
     goals: normalized.goals,
     in_scope: normalized.in_scope,
     out_of_scope: normalized.out_of_scope,
-    notes: normalized.notes
+    notes: normalized.notes,
+    archived: normalized.archived
   };
 }
 
-function deriveEpicStatus(tasks) {
+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.every((task) => task.column === 'done')) return 'done';
   return 'planned';
 }
 
+function isLiveEpic(epicOrShaped) {
+  if (!epicOrShaped) return false;
+  if (epicOrShaped.archived) return false;
+  if (epicOrShaped.status) return LIVE_EPIC_STATUSES.includes(epicOrShaped.status);
+  return true;
+}
+
 function getEpicProgress(tasks) {
   const progress = {
     tasks_total: tasks.length,
@@ -349,7 +426,7 @@ function shapeEpic(epic, tasks = [], options = {}) {
   const childTasks = tasks.filter((task) => task.epic_id === normalized.id);
   const payload = {
     ...normalized,
-    status: deriveEpicStatus(childTasks),
+    status: deriveEpicStatus(childTasks, normalized),
     progress: getEpicProgress(childTasks),
     tasks: childTasks.map((task) => shapeTask(task, { view: 'summary' }))
   };
@@ -359,6 +436,69 @@ function shapeEpic(epic, tasks = [], options = {}) {
   return pickEpicFields(payload, fields);
 }
 
+function filterShapedEpics(shapedEpics, options = {}) {
+  const statusFilter = normalizeString(options.status).toLowerCase() || null;
+  if (statusFilter) {
+    return shapedEpics.filter((epic) => epic.status === statusFilter);
+  }
+
+  // live_only=false: human/GUI board — everything except archived unless include_archived
+  if (options.live_only === false) {
+    if (options.include_archived) return shapedEpics;
+    return shapedEpics.filter((epic) => !epic.archived);
+  }
+
+  // Default (agents): only empty|planned|active
+  const includeArchived = Boolean(options.include_archived);
+  const includeDone = Boolean(options.include_done);
+
+  return shapedEpics.filter((epic) => {
+    if (epic.archived) return includeArchived;
+    if (epic.status === 'done') return includeDone || includeArchived;
+    return isLiveEpic(epic);
+  });
+}
+
+function archivedEpicIdSet(epics) {
+  const set = new Set();
+  for (const epic of epics) {
+    if (epic.archived) set.add(epic.id);
+  }
+  return set;
+}
+
+function nonLiveEpicIdSet(epics, tasks, options = {}) {
+  const includeArchived = Boolean(options.include_archived);
+  const includeDone = Boolean(options.include_done);
+  if (includeArchived && includeDone) return new Set();
+
+  const hidden = new Set();
+  for (const epic of epics) {
+    const childTasks = tasks.filter((task) => task.epic_id === epic.id);
+    const status = deriveEpicStatus(childTasks, epic);
+    if (status === 'archived' && !includeArchived) hidden.add(epic.id);
+    else if (status === 'done' && !includeDone && !includeArchived) hidden.add(epic.id);
+  }
+  return hidden;
+}
+
+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.
+  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) {
+    if (options.include_archived) return tasks;
+    const archivedIds = archivedEpicIdSet(epics);
+    if (archivedIds.size === 0) return tasks;
+    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));
+}
+
 function getProgress(task) {
   const total = task.subtasks.length;
   const done = task.subtasks.filter((subtask) => subtask.done).length;
@@ -459,9 +599,24 @@ async function parseMarkdownTask(filePath, column) {
 }
 
 async function parseJsonTask(filePath, column) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (error.code === 'ENOENT') throw error;
+    throw createKanbanError(
+      'PARSE_ERROR',
+      `Task file ${path.basename(filePath)} could not be read`,
+      'Fix permissions or restore the file from version control',
+      { file: filePath, reason: error.message },
+      false,
+      500
+    );
+  }
+
   let data;
   try {
-    data = JSON.parse(await fs.readFile(filePath, 'utf-8'));
+    data = JSON.parse(raw);
   } catch (error) {
     throw createKanbanError(
       'PARSE_ERROR',
@@ -495,7 +650,7 @@ async function allEpics() {
     try {
       const files = await fs.readdir(colDir);
       const taskFiles = files
-        .filter((file) => file.endsWith('.json') || file.endsWith('.md'))
+        .filter((file) => isTaskOrEpicDataFile(file))
         .sort((left, right) => {
           const leftBase = path.basename(left, path.extname(left));
           const rightBase = path.basename(right, path.extname(right));
@@ -512,6 +667,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}`);
         }
       }
@@ -537,6 +694,7 @@ async function nextEpicNumber() {
   try {
     const files = await fs.readdir(EPICS_DIR);
     for (const file of files) {
+      if (!isTaskOrEpicDataFile(file)) continue;
       const match = file.match(/^E0*(\d+)\.json$/i);
       if (match) ids.push(parseInt(match[1], 10));
     }
@@ -585,7 +743,7 @@ async function listEpicEntities() {
   const epics = [];
   try {
     const files = (await fs.readdir(EPICS_DIR))
-      .filter((file) => file.endsWith('.json'))
+      .filter((file) => isTaskOrEpicDataFile(file) && file.endsWith('.json'))
       .sort((left, right) => left.localeCompare(right));
     for (const file of files) {
       try {
@@ -600,7 +758,7 @@ async function listEpicEntities() {
   return epics;
 }
 
-async function writeEpic(epic) {
+async function writeEpic(epic, { exclusive = false } = {}) {
   const normalized = normalizeEpic(epic);
   if (!normalizeEpicId(normalized.id)) {
     throw createKanbanError(
@@ -614,7 +772,8 @@ async function writeEpic(epic) {
   }
   await ensureBacklogDir();
   const filePath = epicFilePath(normalized.id);
-  await fs.writeFile(filePath, JSON.stringify(serializeEpic(normalized), null, 2) + '\n', 'utf-8');
+  const payload = JSON.stringify(serializeEpic(normalized), null, 2) + '\n';
+  await writeFileAtomic(filePath, payload, { exclusive });
   return parseJsonEpic(filePath);
 }
 
@@ -683,7 +842,9 @@ async function resolveEpicRef(ref, options = {}) {
   }
 
   if (options.createIfMissing) {
-    const created = await doCreateEpic(normalizeString(ref), {});
+    const created = options.skipLock
+      ? await createEpicRecord(normalizeString(ref), {})
+      : await doCreateEpic(normalizeString(ref), {});
     return { epic_id: created.id, epic_group: created.title };
   }
 
@@ -697,7 +858,7 @@ async function resolveEpicRef(ref, options = {}) {
   );
 }
 
-async function doCreateEpic(title, extra = {}) {
+async function createEpicRecord(title, extra = {}) {
   if (!normalizeString(title)) {
     throw createKanbanError(
       'MISSING_REQUIRED_FIELD',
@@ -709,81 +870,175 @@ async function doCreateEpic(title, extra = {}) {
     );
   }
 
-  const nextId = await nextEpicNumber();
-  const epic = normalizeEpic({
-    id: `E${String(nextId).padStart(3, '0')}`,
-    title,
-    created: todayIso(),
-    description: extra.description,
-    goals: extra.goals,
-    in_scope: extra.in_scope,
-    out_of_scope: extra.out_of_scope,
-    notes: extra.notes
-  });
-  return writeEpic(epic);
+  for (let attempt = 0; attempt < 32; attempt++) {
+    const nextId = await nextEpicNumber();
+    const epic = normalizeEpic({
+      id: `E${String(nextId).padStart(3, '0')}`,
+      title,
+      created: todayIso(),
+      description: extra.description,
+      goals: extra.goals,
+      in_scope: extra.in_scope,
+      out_of_scope: extra.out_of_scope,
+      notes: extra.notes
+    });
+    try {
+      return await writeEpic(epic, { exclusive: true });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+  }
+  throw createKanbanError(
+    'CREATE_CONFLICT',
+    'Could not allocate a unique epic id',
+    'Retry the create operation',
+    { title },
+    true,
+    409
+  );
+}
+
+async function doCreateEpic(title, extra = {}) {
+  return withBoardLock(() => createEpicRecord(title, extra));
 }
 
 async function updateEpicEntity(epicId, patch) {
   validatePatch(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
-      );
+  return withBoardLock(async () => {
+    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;
     }
-    next.title = 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
-      );
+    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);
     }
-    next.in_scope = normalizeStringArray(patch.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
-      );
+    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 = normalizeStringArray(patch.out_of_scope);
-  }
-  if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
+    if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
+    if (patch.archived !== undefined) next.archived = Boolean(patch.archived);
 
-  const saved = await writeEpic(next);
+    const saved = await writeEpic(next);
 
-  if (patch.title !== undefined && saved.title !== current.title) {
-    const tasks = await allTasks();
-    for (const task of tasks) {
-      if (task.epic_id === saved.id && task.epic_group !== saved.title) {
-        await updateTask(task.id, { epic_group: saved.title, _skipEpicResolve: true });
+    if (patch.title !== undefined && saved.title !== current.title) {
+      const tasks = await allTasks();
+      for (const task of tasks) {
+        if (task.epic_id === saved.id && task.epic_group !== saved.title) {
+          await updateTaskRecord(task.id, { epic_group: saved.title, _skipEpicResolve: true });
+        }
       }
     }
+
+    return saved;
+  });
+}
+
+async function archiveEpic(epicId) {
+  return updateEpicEntity(epicId, { archived: true });
+}
+
+async function unarchiveEpic(epicId) {
+  return updateEpicEntity(epicId, { archived: false });
+}
+
+async function deleteTaskRecord(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
+    );
+  }
+
+  const column = path.basename(path.dirname(filePath));
+  const task = await parseEpic(filePath, column);
+  await fs.unlink(filePath).catch((error) => {
+    if (error.code !== 'ENOENT') throw error;
+  });
+  await removeOtherTaskCopies(task.id, path.join(BACKLOG, '__none__', `${task.id}.json`));
+
+  return {
+    ok: true,
+    task_id: task.id,
+    task_number: task.task_number,
+    title: task.title,
+    column: task.column
+  };
+}
+
+async function deleteTask(taskId) {
+  return withBoardLock(() => deleteTaskRecord(taskId));
+}
+
+async function deleteEpic(epicId) {
+  return withBoardLock(async () => {
+  const epic = await getEpicEntity(epicId);
+  const tasks = await allTasks();
+  const children = tasks.filter((task) => task.epic_id === epic.id);
+  const deletedTasks = [];
+
+  for (const child of children) {
+    const result = await deleteTaskRecord(child.id);
+    deletedTasks.push({
+      task_id: result.task_id,
+      title: result.title,
+      column: result.column
+    });
   }
 
-  return saved;
+  const filePath = epicFilePath(epic.id);
+  await fs.unlink(filePath).catch((error) => {
+    if (error.code !== 'ENOENT') throw error;
+  });
+
+  return {
+    ok: true,
+    epic_id: epic.id,
+    title: epic.title,
+    deleted_tasks: deletedTasks,
+    deleted_task_count: deletedTasks.length
+  };
+  });
 }
 
 async function migrateEpicGroups(options = {}) {
@@ -854,7 +1109,7 @@ async function findFile(epicId) {
     try {
       const files = await fs.readdir(colDir);
       const candidates = files
-        .filter((file) => (file.endsWith('.json') || file.endsWith('.md'))
+        .filter((file) => isTaskOrEpicDataFile(file)
           && path.basename(file, path.extname(file)) === epicId)
         .sort((left, _right) => (left.endsWith('.json') ? -1 : 1));
       if (candidates[0]) {
@@ -913,12 +1168,34 @@ async function resolveTaskId(input) {
   return String(input);
 }
 
-async function writeTask(task, previousFilePath = null) {
+async function removeOtherTaskCopies(taskId, keepPath) {
+  const keep = path.resolve(keepPath);
+  for (const col of COLS) {
+    const colDir = path.join(BACKLOG, col);
+    try {
+      const files = await fs.readdir(colDir);
+      for (const file of files) {
+        if (!isTaskOrEpicDataFile(file)) continue;
+        if (path.basename(file, path.extname(file)) !== taskId) continue;
+        const candidate = path.join(colDir, file);
+        if (path.resolve(candidate) === keep) continue;
+        await fs.unlink(candidate).catch((error) => {
+          if (error.code !== 'ENOENT') throw error;
+        });
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+async function writeTask(task, previousFilePath = null, { exclusive = false } = {}) {
   const normalized = normalizeTask(task);
   await ensureBacklogDir();
 
   const nextFilePath = path.join(BACKLOG, normalized.column, `${normalized.id}.json`);
-  await fs.writeFile(nextFilePath, JSON.stringify(serializeTask(normalized), null, 2) + '\n', 'utf-8');
+  const payload = JSON.stringify(serializeTask(normalized), null, 2) + '\n';
+  await writeFileAtomic(nextFilePath, payload, { exclusive });
 
   if (previousFilePath && path.resolve(previousFilePath) !== path.resolve(nextFilePath)) {
     await fs.unlink(previousFilePath).catch((error) => {
@@ -926,6 +1203,8 @@ async function writeTask(task, previousFilePath = null) {
     });
   }
 
+  await removeOtherTaskCopies(normalized.id, nextFilePath);
+
   return parseJsonTask(nextFilePath, normalized.column);
 }
 
@@ -945,7 +1224,7 @@ async function migrateAll(options = {}) {
     }
 
     const mdFiles = files
-      .filter((file) => file.endsWith('.md'))
+      .filter((file) => isTaskOrEpicDataFile(file) && file.endsWith('.md'))
       .map((file) => ({
         name: file,
         taskId: path.basename(file, '.md')
@@ -985,6 +1264,7 @@ async function nextTaskNumber() {
     try {
       const files = await fs.readdir(colDir);
       for (const file of files) {
+        if (!isTaskOrEpicDataFile(file)) continue;
         const match = file.match(/^(?:[A-Z]+-)?(\d+)/);
         if (match) ids.push(parseInt(match[1], 10));
       }
@@ -1036,39 +1316,53 @@ async function doCreate(title, column = 'planned', epicRef = '—', extra = {})
 
   validateColumn(column, 'col');
 
-  let epicLink = { epic_id: null, epic_group: '—' };
-  if (!isBlankEpicRef(epicRef)) {
-    epicLink = await resolveEpicRef(epicRef, { createIfMissing: true });
-  } else if (extra.epic_id) {
-    epicLink = await resolveEpicRef(extra.epic_id, { createIfMissing: false });
-  }
+  return withBoardLock(async () => {
+    let epicLink = { epic_id: null, epic_group: '—' };
+    if (!isBlankEpicRef(epicRef)) {
+      epicLink = await resolveEpicRef(epicRef, { createIfMissing: true, skipLock: true });
+    } else if (extra.epic_id) {
+      epicLink = await resolveEpicRef(extra.epic_id, { createIfMissing: false, skipLock: true });
+    }
 
-  const nextId = await nextTaskNumber();
-  const task = normalizeTask({
-    id: String(nextId).padStart(3, '0'),
-    title,
-    column,
-    epic_id: epicLink.epic_id,
-    epic_group: epicLink.epic_group,
-    created: todayIso(),
-    description: extra.description,
-    specs: extra.specs,
-    in_scope: extra.in_scope,
-    out_of_scope: extra.out_of_scope,
-    acceptance_criteria: extra.acceptance_criteria,
-    test_cases: extra.test_cases,
-    subtasks: extra.subtasks,
-    notes: extra.notes,
-    plan: extra.plan,
-    evidence: extra.evidence
+    for (let attempt = 0; attempt < 32; attempt++) {
+      const nextId = await nextTaskNumber();
+      const task = normalizeTask({
+        id: String(nextId).padStart(3, '0'),
+        title,
+        column,
+        epic_id: epicLink.epic_id,
+        epic_group: epicLink.epic_group,
+        created: todayIso(),
+        description: extra.description,
+        specs: extra.specs,
+        in_scope: extra.in_scope,
+        out_of_scope: extra.out_of_scope,
+        acceptance_criteria: extra.acceptance_criteria,
+        test_cases: extra.test_cases,
+        subtasks: extra.subtasks,
+        notes: extra.notes,
+        comments: extra.comments,
+        plan: extra.plan,
+        evidence: extra.evidence
+      });
+      try {
+        return await writeTask(task, null, { exclusive: true });
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+      }
+    }
+    throw createKanbanError(
+      'CREATE_CONFLICT',
+      'Could not allocate a unique task id',
+      'Retry the create operation',
+      { title },
+      true,
+      409
+    );
   });
-
-  return writeTask(task);
 }
 
-async function updateTask(taskId, patch) {
-  validatePatch(patch);
-
+async function updateTaskRecord(taskId, patch) {
   const resolvedId = await resolveTaskId(taskId);
   const previousFilePath = await findFile(resolvedId);
   if (!previousFilePath) {
@@ -1112,7 +1406,12 @@ async function updateTask(taskId, patch) {
         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) });
+        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;
       }
@@ -1189,6 +1488,19 @@ async function updateTask(taskId, patch) {
     next.subtasks = patch.subtasks;
   }
   if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
+  if (patch.comments !== undefined) {
+    if (!Array.isArray(patch.comments)) {
+      throw createKanbanError(
+        'VALIDATION_ERROR',
+        'comments must be an array',
+        'Send comments as an array of comment objects',
+        { field: 'comments' },
+        false,
+        400
+      );
+    }
+    next.comments = patch.comments;
+  }
   if (patch.plan !== undefined) next.plan = patch.plan;
   if (patch.evidence !== undefined) {
     if (!Array.isArray(patch.evidence)) {
@@ -1207,6 +1519,49 @@ async function updateTask(taskId, patch) {
   return writeTask(next, previousFilePath);
 }
 
+async function updateTask(taskId, patch) {
+  validatePatch(patch);
+  return withBoardLock(() => updateTaskRecord(taskId, patch));
+}
+
+async function addComment(taskId, text, author = 'user') {
+  const body = normalizeString(text);
+  if (!body) {
+    throw createKanbanError(
+      'MISSING_REQUIRED_FIELD',
+      'text is required',
+      'Provide a non-empty comment text',
+      { field: 'text' },
+      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)));
+    const comments = normalizeComments(current.comments);
+    const comment = {
+      id: nextCommentId(comments),
+      created: nowIso(),
+      author: normalizeString(author, 'user') || 'user',
+      text: body
+    };
+    const saved = await writeTask({ ...current, comments: [...comments, comment] }, previousFilePath);
+    return { comment, comments: saved.comments, task_id: saved.id };
+  });
+}
+
 async function doMove(epicId, target) {
   try {
     await updateTask(epicId, { column: target });
@@ -1272,6 +1627,7 @@ module.exports = {
   shapeTask,
   shapeEpic,
   updateTask,
+  addComment,
   migrateAll,
   migrateEpicGroups,
   doMove,
@@ -1280,10 +1636,17 @@ module.exports = {
   doCreate,
   doCreateEpic,
   updateEpicEntity,
+  archiveEpic,
+  unarchiveEpic,
+  deleteTask,
+  deleteEpic,
   getEpicEntity,
   listEpicEntities,
   resolveEpicRef,
   taskMatchesEpicFilter,
+  filterShapedEpics,
+  filterTasksForList,
+  isLiveEpic,
   createKanbanError,
   createFieldWarnings,
   createEpicFieldWarnings,
@@ -1297,6 +1660,7 @@ module.exports = {
   STATUS_MAP,
   VIEW_FIELDS,
   EPIC_VIEW_FIELDS,
+  LIVE_EPIC_STATUSES,
   RECOMMENDED_CREATE_FIELDS,
   RECOMMENDED_EPIC_CREATE_FIELDS,
   EPICS_DIR