kanbango 3.2.0 → 3.4.1

package/.ai/lessons.jsonl

@@ -3,3 +3,6 @@
 {"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}
+{"id":"260819-ztl","ts":"2026-08-19","scope":"proj","tags":["config","kanban","validation"],"rule":"DO Field-policy config: skip only ENOENT; invalid JSON/shape must throw CONFIG_INVALID, never silently fall back to def…","when":"config load / required fields","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-19T20:04:53.425Z","sessionID":"ses_feb8269efffe9L33YfwuSnVUVa","added":["260819-ztl"],"bumped":[]}

package/.ait-quality.yml

@@ -0,0 +1,25 @@
+# kanbango quality policy
+# CLI/GUI entrypoints use console.log as user-facing output (not debug leftovers).
+version: 1
+include: []
+exclude:
+  - node_modules/**
+  - backlog/**
+  - examples/**
+languages:
+  - javascript
+  - markdown
+rules:
+  enabled: true
+  debug-leftover: off
+  swallowed-exception: error
+  hidden-fallback: error
+  unsafe-pattern: error
+  placeholder-todo: warning
+  dead-code: warning
+  cognitive-complexity: warning
+  function-length: warning
+  nesting-depth: warning
+  duplicate-blocks: warning
+gate:
+  fail_on: error

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.4.1] - 2026-08-20
+
+### Fixed
+- CLI `kanban mcp` / `npx kanbango mcp` starts the MCP server (was `Unknown command: mcp` → client `-32000 Connection closed`)
+
+## [3.4.0] - 2026-08-20
+
+### Added
+- GUI renders fenced ` ```mermaid ` blocks in task Details and epic info panels (flowchart, sequence, gantt, pie, …)
+- Local Mermaid vendor served from `node_modules` (`/vendor/mermaid.min.js`); dual-export fence parser `fenced-text.js`
+- Soft-fail per diagram: broken Mermaid shows source and does not break the board
+- Dependency `mermaid`; tracked `package-lock.json`
+- Tests: `tests/fenced-text.test.js`, `tests/kanban-mermaid-vendor.test.js`
+- In-process lock + atomic writes for create/update/delete (race-safe board mutations)
+- `.ait-quality.yml` project quality policy (CLI `console.log` treated as UX output)
+
+### Changed
+- Edit mode still shows raw mermaid fences (no live preview)
+
+## [3.3.0] - 2026-08-19
+
+### Note
+- Version 3.3.0 was published on npm; this repo release for Mermaid GUI is **3.4.0**.
+
 ## [3.2.0] - 2026-07-31
 
 ### Added

package/README.md

@@ -169,6 +169,7 @@ Your agent stays in sync with your real board — every change is persisted as J
 | `kanban show <ID>` | Show task details |
 | `kanban add <TITLE>` | Add a new task |
 | `kanban move <ID> <COL>` | Move task |
+| `kanban mcp` | Start MCP server (stdio) |
 | `kanban mcp-init` | Generate MCP config files |
 | `kanban plan <action> --json '{...}'` | Accepted-plan workflow (create/advance/evidence/done/status) |
 

package/bin/kanban.js

@@ -336,6 +336,46 @@ function injectProjectIntoHtml(html, project) {
     .replace(/<h1>Donna Kanban<\/h1>/, `<h1>${safe}</h1>`);
 }
 
+/** Allowlisted GUI vendor files only (no open node_modules). */
+const VENDOR_FILES = {
+  '/vendor/fenced-text.js': {
+    filePath: path.join(__dirname, '..', 'fenced-text.js'),
+    contentType: 'application/javascript; charset=utf-8'
+  },
+  '/vendor/mermaid.min.js': {
+    filePath: path.join(__dirname, '..', 'node_modules', 'mermaid', 'dist', 'mermaid.min.js'),
+    contentType: 'application/javascript; charset=utf-8'
+  }
+};
+
+function sendVendorFile(res, requestPath) {
+  const entry = VENDOR_FILES[requestPath];
+  if (!entry) return false;
+  if (!fs.existsSync(entry.filePath)) {
+    sendJson(res, 404, {
+      error: {
+        code: 'VENDOR_MISSING',
+        message: `Vendor file missing: ${requestPath}`,
+        hint: 'Run npm install in the kanbango package root'
+      }
+    });
+    return true;
+  }
+  res.writeHead(200, {
+    'Content-Type': entry.contentType,
+    'Cache-Control': 'public, max-age=3600'
+  });
+  fs.createReadStream(entry.filePath).pipe(res);
+  return true;
+}
+
+function logGuiPortCleanupError(err) {
+  // Port file may already be gone on shutdown — do not block exit.
+  if (err && err.code !== 'ENOENT') {
+    console.error('gui port cleanup:', err.message || err);
+  }
+}
+
 async function serveWeb(port) {
   const htmlTemplate = fs.readFileSync(path.join(__dirname, '..', 'index.html'), 'utf-8');
   const project = guiRegistry.projectLabel();
@@ -352,6 +392,10 @@ async function serveWeb(port) {
         return;
       }
 
+      if (req.method === 'GET' && sendVendorFile(res, requestPath)) {
+        return;
+      }
+
       if (requestPath === '/api/board') {
         await kanban.migrateEpicGroups();
         const includeArchived = url.searchParams.get('include_archived') === 'true';
@@ -579,8 +623,8 @@ async function serveWeb(port) {
   async function cleanupGuiPortFile() {
     try {
       await guiRegistry.clearGuiPortFile({ pid: process.pid });
-    } catch {
-      // best-effort cleanup
+    } catch (err) {
+      logGuiPortCleanupError(err);
     }
   }
 
@@ -705,6 +749,9 @@ async function main() {
     }
 
     await cliMcpInit({ useNpx, onlyClaude, onlyOpenCode, force });
+  } else if (cmd === 'mcp') {
+    const mcpServer = require('../mcp-server.js');
+    await mcpServer.main();
   } else if (cmd === 'migrate') {
     const dryRun = args.includes('--dry-run');
     await cliMigrate(dryRun);

package/fenced-text.js

@@ -0,0 +1,62 @@
+/**
+ * Split plain text into text / mermaid fence segments.
+ * Dual export: CommonJS (Node tests) + browser global FencedText.
+ */
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.FencedText = factory();
+  }
+})(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  // ```mermaid ... ``` (language case-insensitive). CRLF ok. Other fences stay plain text.
+  var FENCE_RE = /^```([^\r\n`]*)\r?\n([\s\S]*?)^```[ \t]*\r?$/gm;
+
+  function parseFencedText(text) {
+    var source = text == null ? '' : String(text);
+    if (!source) {
+      return [];
+    }
+
+    var segments = [];
+    var lastIndex = 0;
+    var match;
+    FENCE_RE.lastIndex = 0;
+
+    while ((match = FENCE_RE.exec(source)) !== null) {
+      if (match.index > lastIndex) {
+        segments.push({ type: 'text', value: source.slice(lastIndex, match.index) });
+      }
+
+      var lang = String(match[1] || '').trim().toLowerCase();
+      // Strip optional info string after language (e.g. mermaid title="x")
+      if (lang.indexOf(' ') !== -1) {
+        lang = lang.split(/\s+/)[0];
+      }
+      var body = match[2];
+      if (lang === 'mermaid') {
+        segments.push({ type: 'mermaid', value: body.replace(/\s+$/, '') });
+      } else {
+        segments.push({ type: 'text', value: match[0] });
+      }
+
+      lastIndex = match.index + match[0].length;
+    }
+
+    if (lastIndex < source.length) {
+      segments.push({ type: 'text', value: source.slice(lastIndex) });
+    }
+
+    if (segments.length === 0) {
+      segments.push({ type: 'text', value: source });
+    }
+
+    return segments;
+  }
+
+  return {
+    parseFencedText: parseFencedText
+  };
+});

package/index.html

@@ -614,6 +614,45 @@ header h1 { font-size: 14px; font-weight: 700; letter-spacing: -0.2px; }
   color: var(--text);
   white-space: pre-wrap;
 }
+.detail-text .md-text {
+  white-space: pre-wrap;
+}
+.md-mermaid {
+  margin: 8px 0;
+  padding: 10px;
+  background: #f8fafc;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  overflow-x: auto;
+  text-align: center;
+}
+.md-mermaid svg { max-width: 100%; height: auto; }
+.md-mermaid-error {
+  margin: 8px 0;
+  padding: 8px 10px;
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  border-radius: var(--radius);
+  text-align: left;
+}
+.md-mermaid-error .md-err-label {
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: #b91c1c;
+  margin-bottom: 6px;
+}
+.md-mermaid-error pre {
+  margin: 0;
+  font-size: 11px;
+  line-height: 1.4;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--text);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+.sl-epic-text .md-mermaid { margin: 6px 0 0; }
 .detail-list {
   margin: 0;
   padding-left: 18px;
@@ -777,6 +816,8 @@ header h1 { font-size: 14px; font-weight: 700; letter-spacing: -0.2px; }
 
 <div class="toast" id="toast"></div>
 
+<script src="/vendor/fenced-text.js"></script>
+<script src="/vendor/mermaid.min.js"></script>
 <script>
 const COL_DEFS = [
   { id: "icebox",  label: "🧊 Icebox",  icon: "🧊" },
@@ -877,6 +918,7 @@ function render() {
   const sl = document.getElementById("swimlanes");
   sl.innerHTML = "";
   groupTasks(allTasks).forEach(g => sl.appendChild(renderSwimlane(g)));
+  queueMermaidRun();
 }
 
 function groupTasks(tasks) {
@@ -924,11 +966,14 @@ function renderEpicDetailView(entity) {
 
   const hero = el("div", "sl-epic-hero");
   const goals = el("div", "sl-epic-goals");
-  goals.innerHTML = `<div class="sl-epic-label">Goals</div>${
-    entity.goals
-      ? `<div class="sl-epic-text">${escHtml(entity.goals)}</div>`
-      : `<div class="sl-epic-text empty">No goals set</div>`
-  }`;
+  goals.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "Goals" }));
+  if (entity.goals) {
+    const goalsText = el("div", "sl-epic-text");
+    fillRichText(goalsText, entity.goals);
+    goals.appendChild(goalsText);
+  } else {
+    goals.appendChild(Object.assign(el("div", "sl-epic-text empty"), { textContent: "No goals set" }));
+  }
   hero.appendChild(goals);
 
   const rollup = el("div", "sl-epic-rollup");
@@ -945,13 +990,35 @@ function renderEpicDetailView(entity) {
   const body = el("div", "sl-epic-body");
 
   const descCard = el("div", "sl-epic-card");
-  descCard.innerHTML = `<div class="sl-epic-label">Description</div>${
-    entity.description
-      ? `<div class="sl-epic-text">${escHtml(entity.description)}</div>`
-      : `<div class="sl-epic-text empty">No description yet — click Edit epic to add context for agents.</div>`
-  }`;
+  descCard.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "What" }));
+  if (entity.description) {
+    const descText = el("div", "sl-epic-text");
+    fillRichText(descText, entity.description);
+    descCard.appendChild(descText);
+  } else {
+    descCard.appendChild(Object.assign(el("div", "sl-epic-text empty"), {
+      textContent: "No description yet — click Edit epic to add what this initiative does."
+    }));
+  }
   body.appendChild(descCard);
 
+  if (entity.rationale) {
+    const rationaleCard = el("div", "sl-epic-card");
+    rationaleCard.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "Rationale" }));
+    const rationaleText = el("div", "sl-epic-text");
+    fillRichText(rationaleText, entity.rationale);
+    rationaleCard.appendChild(rationaleText);
+    body.appendChild(rationaleCard);
+  }
+  if (entity.outcome) {
+    const outcomeCard = el("div", "sl-epic-card");
+    outcomeCard.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "Outcome" }));
+    const outcomeText = el("div", "sl-epic-text");
+    fillRichText(outcomeText, entity.outcome);
+    outcomeCard.appendChild(outcomeText);
+    body.appendChild(outcomeCard);
+  }
+
   const scopeCard = el("div", "sl-epic-card scope-pair");
   scopeCard.innerHTML = `
     <div>
@@ -968,7 +1035,10 @@ function renderEpicDetailView(entity) {
 
   if (entity.notes) {
     const notes = el("div", "sl-epic-card sl-epic-notes");
-    notes.innerHTML = `<div class="sl-epic-label">Notes</div><div class="sl-epic-text">${escHtml(entity.notes)}</div>`;
+    notes.appendChild(Object.assign(el("div", "sl-epic-label"), { textContent: "Notes" }));
+    const notesText = el("div", "sl-epic-text");
+    fillRichText(notesText, entity.notes);
+    notes.appendChild(notesText);
     panel.appendChild(notes);
   }
 
@@ -980,6 +1050,8 @@ function renderEpicDetailEdit(entity) {
   const dirty = dirtyEpicEdits[entity.id] || {
     title: entity.title || "",
     description: entity.description || "",
+    rationale: entity.rationale || "",
+    outcome: entity.outcome || "",
     goals: entity.goals || "",
     in_scope: (entity.in_scope || []).join("\n"),
     out_of_scope: (entity.out_of_scope || []).join("\n"),
@@ -1010,15 +1082,33 @@ function renderEpicDetailEdit(entity) {
   grid.appendChild(goalsWrap);
 
   const descWrap = el("div", "span2");
-  descWrap.innerHTML = `<label>Description</label>`;
+  descWrap.innerHTML = `<label>What</label>`;
   const descTa = document.createElement("textarea");
   descTa.value = dirty.description;
-  descTa.placeholder = "Context for agents…";
+  descTa.placeholder = "What this initiative does…";
   descTa.style.minHeight = "72px";
   descTa.oninput = () => { dirty.description = descTa.value; dirtyEpicEdits[entity.id] = dirty; };
   descWrap.appendChild(descTa);
   grid.appendChild(descWrap);
 
+  const rationaleWrap = el("div", "span2");
+  rationaleWrap.innerHTML = `<label>Rationale</label>`;
+  const rationaleTa = document.createElement("textarea");
+  rationaleTa.value = dirty.rationale;
+  rationaleTa.placeholder = "Why this approach, not alternatives…";
+  rationaleTa.oninput = () => { dirty.rationale = rationaleTa.value; dirtyEpicEdits[entity.id] = dirty; };
+  rationaleWrap.appendChild(rationaleTa);
+  grid.appendChild(rationaleWrap);
+
+  const outcomeWrap = el("div", "span2");
+  outcomeWrap.innerHTML = `<label>Outcome</label>`;
+  const outcomeTa = document.createElement("textarea");
+  outcomeTa.value = dirty.outcome;
+  outcomeTa.placeholder = "Intended effect / goal…";
+  outcomeTa.oninput = () => { dirty.outcome = outcomeTa.value; dirtyEpicEdits[entity.id] = dirty; };
+  outcomeWrap.appendChild(outcomeTa);
+  grid.appendChild(outcomeWrap);
+
   const inWrap = el("div", "");
   inWrap.innerHTML = `<label>In scope (one per line)</label>`;
   const inTa = document.createElement("textarea");
@@ -1074,6 +1164,8 @@ async function saveEpicEdit(epicId) {
     body: JSON.stringify({
       title: dirty.title.trim(),
       description: dirty.description,
+      rationale: dirty.rationale,
+      outcome: dirty.outcome,
       goals: dirty.goals,
       in_scope: splitLines(dirty.in_scope),
       out_of_scope: splitLines(dirty.out_of_scope),
@@ -1371,6 +1463,8 @@ function renderEditMode(card, epic, colId, shortId) {
   const dirty = dirtyEdits[epic.id] || {
     title: displayTitle,
     description: epic.description || "",
+    rationale: epic.rationale || "",
+    outcome: epic.outcome || "",
     specs: epic.specs || "",
     in_scope: (epic.in_scope || []).join("\n"),
     out_of_scope: (epic.out_of_scope || []).join("\n"),
@@ -1395,14 +1489,22 @@ function renderEditMode(card, epic, colId, shortId) {
   card.appendChild(titleInput);
 
   const meta = el("div", "edit-meta");
-  meta.appendChild(renderEditBlock("Description", dirty.description, value => {
+  meta.appendChild(renderEditBlock("What", dirty.description, value => {
     dirty.description = value;
     dirtyEdits[epic.id] = dirty;
-  }, "Context and implementation plan..."));
+  }, "What we are doing..."));
+  meta.appendChild(renderEditBlock("Rationale", dirty.rationale, value => {
+    dirty.rationale = value;
+    dirtyEdits[epic.id] = dirty;
+  }, "Why this approach, not alternatives..."));
+  meta.appendChild(renderEditBlock("Outcome", dirty.outcome, value => {
+    dirty.outcome = value;
+    dirtyEdits[epic.id] = dirty;
+  }, "Intended effect / goal..."));
   meta.appendChild(renderEditBlock("Specs", dirty.specs, value => {
     dirty.specs = value;
     dirtyEdits[epic.id] = dirty;
-  }, "APIs, constraints, edge cases..."));
+  }, "APIs, constraints, edge cases (how)..."));
   meta.appendChild(renderEditBlock("In Scope", dirty.in_scope, value => {
     dirty.in_scope = value;
     dirtyEdits[epic.id] = dirty;
@@ -1531,6 +1633,8 @@ async function saveEdit(epicId) {
     const origTitle = epic.title.replace(/^[\w.-]+:\s*/, "");
     if (dirty.title !== origTitle) body.title = dirty.title;
     body.description = dirty.description;
+    body.rationale = dirty.rationale;
+    body.outcome = dirty.outcome;
     body.specs = dirty.specs;
     body.in_scope = splitLines(dirty.in_scope);
     body.out_of_scope = splitLines(dirty.out_of_scope);
@@ -1728,7 +1832,13 @@ function splitLines(value) {
 }
 function appendDetailSections(card, epic) {
   if (epic.description) {
-    card.appendChild(renderDetailSection("Description", epic.description));
+    card.appendChild(renderDetailSection("What", epic.description));
+  }
+  if (epic.rationale) {
+    card.appendChild(renderDetailSection("Rationale", epic.rationale));
+  }
+  if (epic.outcome) {
+    card.appendChild(renderDetailSection("Outcome", epic.outcome));
   }
   if (epic.specs) {
     card.appendChild(renderDetailSection("Specs", epic.specs));
@@ -1754,11 +1864,130 @@ function renderDetailSection(label, text) {
   const labelEl = el("div", "detail-label");
   labelEl.textContent = label;
   const textEl = el("div", "detail-text");
-  textEl.textContent = text;
+  fillRichText(textEl, text);
   wrap.appendChild(labelEl);
   wrap.appendChild(textEl);
   return wrap;
 }
+
+// ── Mermaid in detail fields (view mode only) ─────────────────────────────────
+
+let mermaidReady = false;
+let mermaidRunTimer = null;
+let mermaidSeq = 0;
+
+function parseFencedSegments(text) {
+  if (window.FencedText && typeof window.FencedText.parseFencedText === "function") {
+    return window.FencedText.parseFencedText(text);
+  }
+  return text ? [{ type: "text", value: String(text) }] : [];
+}
+
+function fillRichText(container, text) {
+  container.textContent = "";
+  const segments = parseFencedSegments(text);
+  if (segments.length === 0) return;
+
+  segments.forEach(seg => {
+    if (seg.type === "mermaid") {
+      const box = el("div", "md-mermaid");
+      box.dataset.mermaidSource = seg.value;
+      const pre = document.createElement("pre");
+      pre.className = "mermaid";
+      pre.textContent = seg.value;
+      box.appendChild(pre);
+      container.appendChild(box);
+    } else if (seg.value) {
+      const span = el("div", "md-text");
+      span.textContent = seg.value;
+      container.appendChild(span);
+    }
+  });
+}
+
+function showMermaidFallback(box, source, err) {
+  box.className = "md-mermaid-error";
+  box.textContent = "";
+  const label = el("div", "md-err-label");
+  label.textContent = err && err.message
+    ? `Mermaid error: ${err.message}`
+    : "Mermaid render failed";
+  const pre = document.createElement("pre");
+  pre.textContent = source || box.dataset.mermaidSource || "";
+  box.appendChild(label);
+  box.appendChild(pre);
+}
+
+function ensureMermaidInit() {
+  if (mermaidReady) return true;
+  if (typeof mermaid === "undefined" || !mermaid) return false;
+  try {
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: "strict",
+      theme: "neutral"
+    });
+    mermaidReady = true;
+    return true;
+  } catch (err) {
+    console.error("mermaid.initialize failed", err);
+    return false;
+  }
+}
+
+async function runMermaidIn(root) {
+  const scope = root || document;
+  const nodes = [...scope.querySelectorAll("pre.mermaid")].filter(
+    n => !n.dataset.processed && n.textContent.trim()
+  );
+  if (nodes.length === 0) return;
+
+  if (!ensureMermaidInit()) {
+    nodes.forEach(pre => {
+      const box = pre.closest(".md-mermaid") || pre.parentElement;
+      if (box) showMermaidFallback(box, pre.textContent, new Error("mermaid library not loaded"));
+    });
+    return;
+  }
+
+  // Prefer per-node render so one bad diagram never blocks siblings.
+  for (const pre of nodes) {
+    const source = pre.textContent;
+    const box = pre.closest(".md-mermaid") || pre.parentElement;
+    const id = `mmd-${Date.now()}-${++mermaidSeq}`;
+    try {
+      const out = await mermaid.render(id, source);
+      // Board re-render may detach this node while await was in flight.
+      if (!pre.isConnected) continue;
+      const svg = typeof out === "string" ? out : (out && out.svg);
+      if (!svg) throw new Error("empty mermaid output");
+      if (box && box.isConnected) {
+        box.innerHTML = svg;
+        box.dataset.processed = "1";
+      } else if (pre.isConnected) {
+        pre.outerHTML = svg;
+      }
+    } catch (err) {
+      // Remove orphaned error SVG mermaid may leave in <body>
+      const stray = document.getElementById(id);
+      if (stray) stray.remove();
+      const strayD = document.getElementById("d" + id);
+      if (strayD) strayD.remove();
+      if (box) showMermaidFallback(box, source, err);
+      else {
+        pre.dataset.processed = "error";
+        pre.title = (err && err.message) || "mermaid error";
+      }
+    }
+  }
+}
+
+function queueMermaidRun(root) {
+  clearTimeout(mermaidRunTimer);
+  mermaidRunTimer = setTimeout(() => {
+    runMermaidIn(root).catch(err => console.error("mermaid run failed", err));
+  }, 0);
+}
 function renderDetailListSection(label, items, extraClass) {
   const wrap = el("div", extraClass ? `detail-section ${extraClass}` : "detail-section");
   const labelEl = el("div", "detail-label");

package/kanban.js

@@ -121,6 +121,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];
 }
@@ -536,9 +573,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 +624,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 +641,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 +668,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 +717,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 +732,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 +746,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 +816,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 +832,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 +844,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 +950,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 +969,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 +980,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 +1012,7 @@ async function deleteEpic(epicId) {
     deleted_tasks: deletedTasks,
     deleted_task_count: deletedTasks.length
   };
+  });
 }
 
 async function migrateEpicGroups(options = {}) {
@@ -998,7 +1083,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 +1142,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 +1177,8 @@ async function writeTask(task, previousFilePath = null) {
     });
   }
 
+  await removeOtherTaskCopies(normalized.id, nextFilePath);
+
   return parseJsonTask(nextFilePath, normalized.column);
 }
 
@@ -1089,7 +1198,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 +1238,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 +1290,52 @@ 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,
+        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 +1379,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;
       }
@@ -1351,6 +1479,11 @@ async function updateTask(taskId, patch) {
   return writeTask(next, previousFilePath);
 }
 
+async function updateTask(taskId, patch) {
+  validatePatch(patch);
+  return withBoardLock(() => updateTaskRecord(taskId, patch));
+}
+
 async function doMove(epicId, target) {
   try {
     await updateTask(epicId, { column: target });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanbango",
-  "version": "3.2.0",
+  "version": "3.4.1",
   "description": "JSON-first local Kanban board with web GUI, CLI, and MCP server",
   "main": "index.js",
   "bin": {
@@ -36,6 +36,7 @@
     "node": ">=16.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "mermaid": "^11.17.0"
   }
 }

package/tests/run.js

@@ -18,7 +18,10 @@ runNode(path.join('tests', 'update-tasks.test.js'), [], 'Update tasks 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');
+runNode(path.join('tests', 'fenced-text.test.js'), [], 'Fenced text test');
+runNode(path.join('tests', 'kanban-mermaid-vendor.test.js'), [], 'Kanban mermaid vendor route test');
 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');