kanbango 3.2.0 → 3.3.0

package/.ai/lessons.jsonl

@@ -3,3 +3,5 @@
 {"id":"260729-5eo","ts":"2026-07-29","scope":"proj","tags":["processes","mcp","ownership"],"rule":"DO Track process ownership before stopping or cleaning up discovered services","when":"gui-process management","sev":2,"hits":1}
 {"id":"260729-1ch","ts":"2026-07-29","scope":"proj","tags":["gui","process","mcp"],"rule":"DO GUI/MCP stop must only SIGTERM processes spawned by the current process; treat port-file PIDs as external_running","when":"gui-process management","sev":2,"hits":1}
 {"id":"260731-o6g","ts":"2026-07-31","scope":"proj","tags":["kanban","epics","mcp"],"rule":"DO Default list/list_epics hide done+archived; hard-delete cascades epic children; archive is reversible flag","when":"kanban cleanup context","sev":2,"hits":1}
+{"id":"260803-b27","ts":"2026-08-03","scope":"proj","tags":["tests","race","fs"],"rule":"DO Serialize board file mutations with an in-process lock and atomic write (temp+rename/link); race tests should assert…","when":"kanban concurrent IO","sev":2,"hits":1}
+{"id":"260813-9t0","ts":"2026-08-13","scope":"proj","tags":["mcp","errors","dx"],"rule":"DO MCP missing-field errors: put Valid list + Example JSON + sent keys in message so the agent can retry without guessi…","when":"MCP tool validation / agent-facing erro…","sev":2,"hits":1}

package/.ai/retro/last-run.json

@@ -1 +1 @@
-{"ts":"2026-07-31T13:58:00.629Z","sessionID":"ses_04792cf77ffec14LhSNoSJReg9","added":["260731-o6g"],"bumped":[]}
+{"ts":"2026-08-13T06:43:28.413Z","sessionID":"ses_038ddd435ffeginZz7W4t3X27v","added":["260813-9t0"],"bumped":[]}

package/.opencode/plans/action-error-recipe.md

@@ -0,0 +1,121 @@
+# Action error recipe (implement)
+
+Status: approved (user said go). Plan mode blocked code edits — switch to **build** and apply.
+
+## Goal
+Missing/empty/unknown `action` on `kanban_manage` / `kanban_gui`: **message** is a full retry recipe (Valid + Example JSON + sent keys).
+
+## Files
+1. `mcp-server.js` — replace `requireToolAction`; add helpers; unknown-action defaults
+2. `tests/mcp-server.test.js` — assert recipe content
+3. `CHANGELOG.md` — one-line unreleased note
+
+## mcp-server.js
+
+Replace current `requireToolAction` block (after `GUI_ACTIONS`) with:
+
+```js
+const ACTION_EXAMPLES = {
+  kanban_manage: '{"action":"create","title":"Ship image","col":"planned"}',
+  kanban_gui: '{"action":"status"}'
+};
+
+function receivedKeys(args) {
+  return Object.keys(args && typeof args === 'object' ? args : {});
+}
+
+function actionRecipeMessage(toolName, allowed, opts = {}) {
+  const keys = opts.received_keys || [];
+  const example = ACTION_EXAMPLES[toolName] || `{"action":"${allowed[0]}"}`;
+  const lines = [];
+  if (opts.kind === 'unknown') {
+    lines.push(`Unknown action "${opts.action}" on ${toolName}.`);
+  } else {
+    lines.push(`Missing required top-level field "action" on ${toolName}.`);
+  }
+  lines.push('Pass action next to other args (not nested under params).');
+  lines.push(`Valid: ${allowed.join(', ')}.`);
+  lines.push(`Example: ${example}`);
+  lines.push(keys.length > 0 ? `You sent keys: ${keys.join(', ')}` : 'You sent keys: (none)');
+  return lines.join(' ');
+}
+
+function actionRecipeHint() {
+  return [
+    'Retry the same tool with top-level action set to one Valid value.',
+    'Common mistake: omitting action, or putting it under params (jira/gitlab style) — kanban uses top-level action.'
+  ].join(' ');
+}
+
+function requireToolAction(args, allowed, toolName) {
+  const action = args && args.action;
+  const keys = receivedKeys(args);
+  if (action === undefined || action === null || action === '') {
+    throw kanban.createKanbanError(
+      'MISSING_REQUIRED_FIELD',
+      actionRecipeMessage(toolName, allowed, {
+        kind: 'missing',
+        received_keys: keys,
+        action: action === undefined ? null : action
+      }),
+      actionRecipeHint(),
+      {
+        field: 'action',
+        tool: toolName,
+        received_keys: keys,
+        allowed_actions: allowed,
+        action: action === undefined ? null : action
+      },
+      false,
+      400
+    );
+  }
+  return action;
+}
+
+function unknownToolAction(action, args, allowed, toolName) {
+  const keys = receivedKeys(args);
+  return invalidRequest(
+    actionRecipeMessage(toolName, allowed, { kind: 'unknown', action, received_keys: keys }),
+    actionRecipeHint(),
+    {
+      field: 'action',
+      tool: toolName,
+      action,
+      received_keys: keys,
+      allowed_actions: allowed
+    }
+  );
+}
+```
+
+Manage default: `throw unknownToolAction(action, args, MANAGE_ACTIONS, 'kanban_manage');`  
+GUI default: `throw unknownToolAction(action, args, GUI_ACTIONS, 'kanban_gui');`
+
+## tests/mcp-server.test.js
+
+Assert on missing/empty/unknown/gui:
+- message includes `Missing required top-level field "action"` (or `Unknown action "nope"`)
+- `Valid:` + key actions + `Example:` + `"action":`
+- sent keys line
+- `details.allowed_actions`
+- no `undefined` in message
+- codes unchanged: MISSING_REQUIRED_FIELD / VALIDATION_ERROR
+
+## CHANGELOG
+
+```md
+### Fixed
+- MCP `kanban_manage` / `kanban_gui`: missing/empty/unknown `action` errors put a full retry recipe in `message` (Valid list + Example JSON + sent keys); missing/empty use `MISSING_REQUIRED_FIELD` instead of `Unknown action: undefined`
+```
+
+## Verify
+```bash
+node tests/mcp-server.test.js
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kanban_manage","arguments":{"title":"x"}}}' | node mcp-server.js
+```
+
+## Acceptance
+- [ ] Missing action message is copy-paste retry recipe
+- [ ] Unknown action same clarity
+- [ ] Tests green

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-08-13
+
+### Added
+- Task comments: append-only `comments[]` on tasks; MCP `comment_add` (`task_id` + `text`, optional `author`); CLI `kanban comment <ID> <text> [--author NAME]`
+- Comments included in `execution` / `full` task views (omitted from `summary`)
+
+### Fixed
+- MCP `kanban_manage` / `kanban_gui`: missing/empty/unknown `action` errors put a full retry recipe in `message` (Valid list + Example JSON + sent keys); missing/empty use `MISSING_REQUIRED_FIELD` instead of `Unknown action: undefined`
+
 ## [3.2.0] - 2026-07-31
 
 ### Added

package/README.md

@@ -152,7 +152,7 @@ Once connected, your agent gets access to these tools:
 | Tool | What it does |
 |------|-------------|
 | `kanban_read` | List/show tasks (`view=summary` by default — cheap) |
-| `kanban_manage` | Create, move, update, plan_* workflow |
+| `kanban_manage` | Create, move, update, comment_add, plan_* workflow |
 | `kanban_gui` | Start / status / stop (stop only kills GUI this MCP started) |
 
 **Token tip for agents:** rules ship inside MCP tool descriptions (`agent-playbook.js`). Optional: `kanban_read` → `operation: "help"`. Human setup notes: [LLM_AGENTS.md](./LLM_AGENTS.md).
@@ -170,6 +170,7 @@ Your agent stays in sync with your real board — every change is persisted as J
 | `kanban add <TITLE>` | Add a new task |
 | `kanban move <ID> <COL>` | Move task |
 | `kanban mcp-init` | Generate MCP config files |
+| `kanban comment <ID> <text> [--author NAME]` | Append a comment to a task |
 | `kanban plan <action> --json '{...}'` | Accepted-plan workflow (create/advance/evidence/done/status) |
 
 ## Web GUI

package/agent-playbook.js

@@ -10,10 +10,10 @@ const DROP_IN_RULE = [
   '- list: col filter, view=summary; keep task_ids; no full-board re-list after writes',
   '- list_epics default = live only (hides done + archived); include_archived / status to widen',
   '- list tasks default hides tasks under done/archived epics; show/show_epic by id always works',
-  '- show: view=execution while coding; full only if needed',
+  '- show: view=execution while coding (includes comments); full only if needed',
   '- epic_create with description/goals; create tasks with epic=E001 (prefer id)',
   '- create once with description,specs,in_scope,out_of_scope,acceptance_criteria',
-  '- move/update/delete: return=none; subtasks=full array replace',
+  '- move/update/delete: return=none; subtasks=full array replace; comment_add: task_id+text',
   '- cleanup: delete (task), epic_delete (cascade tasks), epic_archive / epic_unarchive',
   '- non-trivial: plan_create → plan_advance → plan_evidence (real tests, truncated logs) → plan_done',
   '- gui: status before start; stop only owned; external_running = do not kill'
@@ -23,7 +23,7 @@ const TOOL_DESCRIPTIONS = {
   kanban_read: [
     'Read board. TOKEN RULES: list defaults to view=summary (id/title/col/progress only).',
     'Hierarchy: epic (container/context) → task (work) → subtasks (steps).',
-    'Always pass col when possible. Prefer show+view=execution over full.',
+    'Always pass col when possible. Prefer show+view=execution over full (includes comments).',
     'list_epics default live only (empty|planned|active; hides done+archived).',
     'Pass include_archived=true or status=done|archived to see closed initiatives.',
     'list hides tasks under done/archived epics unless include_archived/include_done; show/show_epic by id always works.',
@@ -36,13 +36,13 @@ const TOOL_DESCRIPTIONS = {
     'Write board / plan. TOKEN RULES: one create with all planning fields beats many updates;',
     'after write use return=none (or summary). Do not dump full task unless needed.',
     'Actions: create|move|update|delete (daily); epic_create|epic_update|epic_archive|epic_unarchive|epic_delete;',
-    'plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
+    'comment_add (append-only history); plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
     'epic_create: title + description/goals/in_scope/out_of_scope. Link tasks via epic=E001.',
     'delete: task_id (hard remove). epic_delete: epic_id, always cascades child tasks.',
     'epic_archive/epic_unarchive: epic_id — hide/restore initiative without deleting history.',
     'create/plan_create: title required; also send description,specs,in_scope,out_of_scope,acceptance_criteria',
     '(missing → warnings, not failure). move: task_id+column. update: task_id + fields or subtasks[] full list',
-    '(no toggle). plan_evidence needs real test run: diff,test_command,stdout,stderr,exit_code — truncate logs.',
+    '(no toggle). comment_add: task_id+text, optional author. plan_evidence needs real test run: diff,test_command,stdout,stderr,exit_code — truncate logs.',
     'Example create: {"action":"create","title":"Ship image","epic":"E001","description":"...","specs":"...",',
     '"in_scope":["CLI"],"out_of_scope":["GUI"],"acceptance_criteria":["npm test passes"],"col":"planned"}'
   ].join(' '),
@@ -63,7 +63,8 @@ const MUST_CONTAIN = [
   'subtasks',
   'epic_create',
   'epic_archive',
-  'epic_delete'
+  'epic_delete',
+  'comment_add'
 ];
 
 function playbookHelpPayload() {

package/bin/kanban.js

@@ -789,6 +789,18 @@ async function main() {
     await cliAdd(args[1], column, epicGroup);
   } else if (cmd === 'plan' && args[1] && args[2] === '--json') {
     await cliPlan(args[1], parseJsonPayload(args[3]));
+  } else if (cmd === 'comment' && args[1] && args[2]) {
+    let author = 'user';
+    for (let i = 3; i < args.length; i++) {
+      if (args[i] === '--author' && args[i + 1]) author = args[++i];
+    }
+    try {
+      const added = await kanban.addComment(args[1], args[2], author);
+      console.log(JSON.stringify({ ok: true, task_id: added.task_id, comment_id: added.comment.id, count: added.comments.length }));
+    } catch (error) {
+      console.error(`✗ ${error.message}`);
+      process.exit(1);
+    }
   } else {
     console.error('Unknown command:', cmd);
     process.exit(1);

package/kanban.js

@@ -41,7 +41,8 @@ const VIEW_FIELDS = {
     'out_of_scope',
     'acceptance_criteria',
     'test_cases',
-    'subtasks'
+    'subtasks',
+    'comments'
   ],
   full: [
     'task_number',
@@ -58,7 +59,8 @@ const VIEW_FIELDS = {
     'acceptance_criteria',
     'test_cases',
     'subtasks',
-    'notes'
+    'notes',
+    'comments'
   ]
 };
 
@@ -121,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];
 }
@@ -216,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) => ({
@@ -255,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)
@@ -280,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
@@ -536,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',
@@ -572,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));
@@ -589,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}`);
         }
       }
@@ -614,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));
     }
@@ -662,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 {
@@ -677,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(
@@ -691,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);
 }
 
@@ -760,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 };
   }
 
@@ -774,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',
@@ -786,82 +870,102 @@ 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.archived !== undefined) next.archived = Boolean(patch.archived);
+    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;
+    return saved;
+  });
 }
 
 async function archiveEpic(epicId) {
@@ -872,7 +976,7 @@ async function unarchiveEpic(epicId) {
   return updateEpicEntity(epicId, { archived: false });
 }
 
-async function deleteTask(taskId) {
+async function deleteTaskRecord(taskId) {
   const resolvedId = await resolveTaskId(taskId);
   const filePath = await findFile(resolvedId);
   if (!filePath) {
@@ -891,6 +995,7 @@ async function deleteTask(taskId) {
   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,
@@ -901,14 +1006,19 @@ async function deleteTask(taskId) {
   };
 }
 
+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 deleteTask(child.id);
+    const result = await deleteTaskRecord(child.id);
     deletedTasks.push({
       task_id: result.task_id,
       title: result.title,
@@ -928,6 +1038,7 @@ async function deleteEpic(epicId) {
     deleted_tasks: deletedTasks,
     deleted_task_count: deletedTasks.length
   };
+  });
 }
 
 async function migrateEpicGroups(options = {}) {
@@ -998,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]) {
@@ -1057,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) => {
@@ -1070,6 +1203,8 @@ async function writeTask(task, previousFilePath = null) {
     });
   }
 
+  await removeOtherTaskCopies(normalized.id, nextFilePath);
+
   return parseJsonTask(nextFilePath, normalized.column);
 }
 
@@ -1089,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')
@@ -1129,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));
       }
@@ -1180,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) {
@@ -1256,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;
       }
@@ -1333,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)) {
@@ -1351,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 });
@@ -1416,6 +1627,7 @@ module.exports = {
   shapeTask,
   shapeEpic,
   updateTask,
+  addComment,
   migrateAll,
   migrateEpicGroups,
   doMove,

package/mcp-server.js

@@ -76,6 +76,101 @@ function invalidRequest(message, hint, details) {
   return kanban.createKanbanError('VALIDATION_ERROR', message, hint, details, false, 400);
 }
 
+const MANAGE_ACTIONS = [
+  'create',
+  'move',
+  'update',
+  'delete',
+  'epic_create',
+  'epic_update',
+  'epic_archive',
+  'epic_unarchive',
+  'epic_delete',
+  'plan_create',
+  'plan_advance',
+  'plan_evidence',
+  'plan_done',
+  'plan_status',
+  'comment_add'
+];
+
+const GUI_ACTIONS = ['start', 'stop', 'status'];
+
+const ACTION_EXAMPLES = {
+  kanban_manage: '{"action":"create","title":"Ship image","col":"planned"}',
+  kanban_gui: '{"action":"status"}'
+};
+
+function receivedKeys(args) {
+  return Object.keys(args && typeof args === 'object' ? args : {});
+}
+
+function actionRecipeMessage(toolName, allowed, opts = {}) {
+  const keys = opts.received_keys || [];
+  const example = ACTION_EXAMPLES[toolName] || `{"action":"${allowed[0]}"}`;
+  const lines = [];
+
+  if (opts.kind === 'unknown') {
+    lines.push(`Unknown action "${opts.action}" on ${toolName}.`);
+  } else {
+    lines.push(`Missing required top-level field "action" on ${toolName}.`);
+  }
+
+  lines.push('Pass action next to other args (not nested under params).');
+  lines.push(`Valid: ${allowed.join(', ')}.`);
+  lines.push(`Example: ${example}`);
+  lines.push(keys.length > 0 ? `You sent keys: ${keys.join(', ')}` : 'You sent keys: (none)');
+  return lines.join(' ');
+}
+
+function actionRecipeHint() {
+  return [
+    'Retry the same tool with top-level action set to one Valid value.',
+    'Common mistake: omitting action, or putting it under params (jira/gitlab style) — kanban uses top-level action.'
+  ].join(' ');
+}
+
+function requireToolAction(args, allowed, toolName) {
+  const action = args && args.action;
+  const keys = receivedKeys(args);
+  if (action === undefined || action === null || action === '') {
+    throw kanban.createKanbanError(
+      'MISSING_REQUIRED_FIELD',
+      actionRecipeMessage(toolName, allowed, {
+        kind: 'missing',
+        received_keys: keys,
+        action: action === undefined ? null : action
+      }),
+      actionRecipeHint(),
+      {
+        field: 'action',
+        tool: toolName,
+        received_keys: keys,
+        allowed_actions: allowed,
+        action: action === undefined ? null : action
+      },
+      false,
+      400
+    );
+  }
+  return action;
+}
+
+function unknownToolAction(action, args, allowed, toolName) {
+  const keys = receivedKeys(args);
+  return invalidRequest(
+    actionRecipeMessage(toolName, allowed, { kind: 'unknown', action, received_keys: keys }),
+    actionRecipeHint(),
+    {
+      field: 'action',
+      tool: toolName,
+      action,
+      received_keys: keys,
+      allowed_actions: allowed
+    }
+  );
+}
+
 function serializeResult(result) {
   if (typeof result === 'string') return result;
 
@@ -370,23 +465,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             action: {
               type: 'string',
-              enum: [
-                'create',
-                'move',
-                'update',
-                'delete',
-                'epic_create',
-                'epic_update',
-                'epic_archive',
-                'epic_unarchive',
-                'epic_delete',
-                'plan_create',
-                'plan_advance',
-                'plan_evidence',
-                'plan_done',
-                'plan_status'
-              ],
-              description: 'create|move|update|delete daily; epic_create|epic_update|epic_archive|epic_unarchive|epic_delete; plan_* multi-step'
+              enum: MANAGE_ACTIONS,
+              description: 'create|move|update|delete daily; epic_*; plan_*; comment_add'
             },
             title: {
               type: 'string',
@@ -456,9 +536,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Freeform notes'
             },
+            text: {
+              type: 'string',
+              description: 'Required for comment_add. Non-empty comment body.'
+            },
+            author: {
+              type: 'string',
+              description: 'Optional comment author (default user). e.g. kocur-reviewer, worker'
+            },
             task_id: {
               type: 'string',
-              description: "Required for move/update/delete/plan_* except plan_create. '014' or '14'."
+              description: "Required for move/update/delete/comment_add/plan_* except plan_create. '014' or '14'."
             },
             column: {
               type: 'string',
@@ -520,7 +608,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {
             action: {
               type: 'string',
-              enum: ['start', 'stop', 'status'],
+              enum: GUI_ACTIONS,
               description: 'start | stop (owned only) | status'
             },
             port: {
@@ -626,7 +714,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'kanban_manage': {
-        const action = args.action;
+        const action = requireToolAction(args, MANAGE_ACTIONS, 'kanban_manage');
         const returnShape = normalizeReturnShape(args.return);
 
         switch (action) {
@@ -824,18 +912,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             result = await plan.status(args.task_id);
             break;
 
+          case 'comment_add': {
+            if (!args.task_id) {
+              throw invalidRequest(
+                "task_id is required for 'comment_add'",
+                'Provide a task ID',
+                { action }
+              );
+            }
+            if (!args.text) {
+              throw invalidRequest(
+                "text is required for 'comment_add'",
+                'Provide a non-empty comment body',
+                { action }
+              );
+            }
+            const added = await kanban.addComment(args.task_id, args.text, args.author);
+            result = returnShape === 'none'
+              ? { ok: true, comment_id: added.comment.id }
+              : returnShape === 'full'
+                ? added
+                : { ok: true, task_id: added.task_id, comment_id: added.comment.id, count: added.comments.length };
+            break;
+          }
+
           default:
-            throw invalidRequest(
-              `Unknown action: ${action}`,
-              'Use create, move, update, delete, epic_create, epic_update, epic_archive, epic_unarchive, epic_delete, plan_create, plan_advance, plan_evidence, plan_done, or plan_status',
-              { action }
-            );
+            throw unknownToolAction(action, args, MANAGE_ACTIONS, 'kanban_manage');
         }
         break;
       }
 
       case 'kanban_gui': {
-        const action = args.action;
+        const action = requireToolAction(args, GUI_ACTIONS, 'kanban_gui');
 
         switch (action) {
           case 'start': {
@@ -851,11 +959,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             break;
           }
           default:
-            throw invalidRequest(
-              `Unknown action: ${action}`,
-              'Use one of: start, stop, status',
-              { action }
-            );
+            throw unknownToolAction(action, args, GUI_ACTIONS, 'kanban_gui');
         }
         break;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanbango",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "JSON-first local Kanban board with web GUI, CLI, and MCP server",
   "main": "index.js",
   "bin": {

package/tests/run.js

@@ -15,6 +15,7 @@ function runNode(scriptPath, args, label) {
 
 runNode(path.join('bin', 'kanban.js'), ['list', '--json'], 'CLI list');
 runNode(path.join('tests', 'update-tasks.test.js'), [], 'Update tasks test');
+runNode(path.join('tests', 'comments.test.js'), [], 'Comments test');
 runNode(path.join('tests', 'read-views.test.js'), [], 'Read views test');
 runNode(path.join('tests', 'mcp-server.test.js'), [], 'MCP server test');
 runNode(path.join('tests', 'gui-port.test.js'), [], 'GUI port test');
@@ -22,3 +23,4 @@ runNode(path.join('tests', 'plan-workflow.test.js'), [], 'Plan workflow test');
 runNode(path.join('tests', 'agent-playbook.test.js'), [], 'Agent playbook test');
 runNode(path.join('tests', 'epics.test.js'), [], 'Epics test');
 runNode(path.join('tests', 'delete-archive.test.js'), [], 'Delete/archive test');
+runNode(path.join('tests', 'race-conditions.test.js'), [], 'Race conditions test');