kanbango 3.3.0 → 3.5.0

package/.ai/lessons.jsonl

@@ -5,3 +5,4 @@
 {"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-08-13T06:43:28.413Z","sessionID":"ses_038ddd435ffeginZz7W4t3X27v","added":["260813-9t0"],"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/AGENTS.md

@@ -11,6 +11,8 @@ Source of truth: `agent-playbook.js` (also MCP tool descriptions + `kanban_read`
 - 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 task returns `epic_goals` (parent compass; `""` if none) — check drift vs goal
+- log architecture decisions: `update` `adr={decision,why}` append; `show_epic` full rolls up `adrs`
 - 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 (no toggle)

package/CHANGELOG.md

@@ -7,14 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [3.3.0] - 2026-08-13
+## [3.5.0] - 2026-08-24
 
 ### 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`)
+- GUI cockpit layout: rail of initiatives, NOW panel for `active`, columns icebox/planned/done, paper document for task and epic
+- Paper shows spec, in/out scope, AC, steps; read-only `adr[]` and `evidence[]` when present
+- Task `show` injects parent `epic_goals` (empty string when none) as a compass
+- Task `adr[]` with append via `update adr={decision,why}`; `show_epic` full rolls up child `adrs`
+- Tests: `tests/gui-cockpit.test.js`, `tests/kanban-epic-goals-adr.test.js`
+
+### Changed
+- GUI no longer uses epic swimlanes; epics filter the board from the rail
+- Active is NOW, not a fourth board column
+
+## [3.4.1] - 2026-08-20
 
 ### 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`
+- 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
 

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, comment_add, plan_* workflow |
+| `kanban_manage` | Create, move, update, 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).
@@ -169,8 +169,8 @@ 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 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,12 @@ 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 (includes comments); full only if needed',
+  '- show: view=execution while coding; full only if needed',
+  '- show task returns epic_goals (parent compass); empty string if no epic/goals — check drift vs goal',
+  '- log architecture decisions: update adr={decision,why} append; show_epic full rolls up adrs',
   '- 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; comment_add: task_id+text',
+  '- move/update/delete: return=none; subtasks=full array replace',
   '- 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 +25,9 @@ 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 (includes comments).',
+    'Always pass col when possible. Prefer show+view=execution over full.',
+    'show task (planning/execution/full) includes epic_goals (parent epic goals; "" if none) — use as compass; check progress toward goal.',
+    'execution/full also include adr[]; show_epic full rolls up child adrs (not stored on epic file).',
     '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 +40,14 @@ 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;',
-    'comment_add (append-only history); plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
+    '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.',
+    'Log architecture decisions on the task: update with adr={decision,why} appends one entry (why this choice).',
     '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). comment_add: task_id+text, optional author. plan_evidence needs real test run: diff,test_command,stdout,stderr,exit_code — truncate logs.',
+    '(no toggle). 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(' '),
@@ -64,7 +69,8 @@ const MUST_CONTAIN = [
   'epic_create',
   'epic_archive',
   'epic_delete',
-  'comment_add'
+  'epic_goals',
+  'adr'
 ];
 
 function playbookHelpPayload() {

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);
@@ -789,18 +836,6 @@ 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/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
+  };
+});