kanbango 3.4.1 → 3.6.2

package/index.js

@@ -10,12 +10,14 @@
 
 const kanban = require('./kanban.js');
 const plan = require('./plan.js');
+const workflow = require('./workflow.js');
 const guiRegistry = require('./gui-registry.js');
 const playbook = require('./agent-playbook.js');
 
 module.exports = {
   kanban,
   plan,
+  workflow,
   guiRegistry,
   playbook,
 };

package/kanban.js

@@ -3,13 +3,27 @@ const path = require('path');
 
 const BACKLOG = path.join(process.cwd(), 'backlog');
 const EPICS_DIR = path.join(BACKLOG, 'epics');
-const COLS = ['active', 'planned', 'icebox', 'done'];
+const COLS = ['active', 'planned', 'icebox', 'testing', 'review', 'done'];
 const STATUS_MAP = {
   active: 'in_progress',
   planned: 'planned',
   icebox: 'icebox',
+  testing: 'testing',
+  review: 'review',
   done: 'done'
 };
+const WORKFLOW_STAGES = ['testing', 'review'];
+const WORKFLOW_STATUSES = ['idle', 'running', 'pass', 'fail', 'blocked'];
+const EVIDENCE_VERDICTS = ['pass', 'fail', 'blocked', ''];
+// Agent/human move contract. Same column is always a no-op.
+const COLUMN_TRANSITIONS = {
+  icebox: ['planned'],
+  planned: ['active', 'icebox', 'testing'],
+  active: ['planned', 'testing', 'icebox'],
+  testing: ['active', 'review'],
+  review: ['active', 'done'],
+  done: ['active']
+};
 const VIEW_FIELDS = {
   summary: ['task_number', 'title', 'column', 'epic_id', 'epic_group', 'created', 'progress'],
   planning: [
@@ -18,6 +32,7 @@ const VIEW_FIELDS = {
     'column',
     'epic_id',
     'epic_group',
+    'epic_goals',
     'created',
     'progress',
     'description',
@@ -33,6 +48,7 @@ const VIEW_FIELDS = {
     'column',
     'epic_id',
     'epic_group',
+    'epic_goals',
     'created',
     'progress',
     'description',
@@ -41,7 +57,11 @@ const VIEW_FIELDS = {
     'out_of_scope',
     'acceptance_criteria',
     'test_cases',
-    'subtasks'
+    'subtasks',
+    'adr',
+    'evidence',
+    'plan',
+    'workflow'
   ],
   full: [
     'task_number',
@@ -49,6 +69,7 @@ const VIEW_FIELDS = {
     'column',
     'epic_id',
     'epic_group',
+    'epic_goals',
     'created',
     'progress',
     'description',
@@ -58,7 +79,11 @@ const VIEW_FIELDS = {
     'acceptance_criteria',
     'test_cases',
     'subtasks',
-    'notes'
+    'adr',
+    'notes',
+    'evidence',
+    'plan',
+    'workflow'
   ]
 };
 
@@ -88,7 +113,8 @@ const EPIC_VIEW_FIELDS = {
     'in_scope',
     'out_of_scope',
     'notes',
-    'tasks'
+    'tasks',
+    'adrs'
   ]
 };
 
@@ -255,14 +281,93 @@ function normalizeSubtasks(value) {
 
 function normalizeEvidence(value) {
   if (!Array.isArray(value)) return [];
-  return value.map((item) => ({
-    diff: normalizeString(item && item.diff),
-    test_command: normalizeString(item && item.test_command),
-    stdout: normalizeString(item && item.stdout),
-    stderr: normalizeString(item && item.stderr),
-    exit_code: Number.isInteger(item && item.exit_code) ? item.exit_code : null,
-    created: normalizeString(item && item.created) || todayIso()
-  }));
+  return value.map((item) => {
+    const stage = normalizeString(item && item.stage);
+    const verdict = normalizeString(item && item.verdict);
+    return {
+      diff: normalizeString(item && item.diff),
+      test_command: normalizeString(item && item.test_command),
+      stdout: normalizeString(item && item.stdout),
+      stderr: normalizeString(item && item.stderr),
+      exit_code: Number.isInteger(item && item.exit_code) ? item.exit_code : null,
+      created: normalizeString(item && item.created) || todayIso(),
+      stage: WORKFLOW_STAGES.includes(stage) || stage === 'plan' ? stage : '',
+      agent: normalizeString(item && item.agent),
+      verdict: EVIDENCE_VERDICTS.includes(verdict) ? verdict : '',
+      summary: normalizeString(item && item.summary)
+    };
+  });
+}
+
+function normalizeWorkflow(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const stage = normalizeString(value.stage);
+  const status = normalizeString(value.status);
+  const agent = normalizeString(value.agent);
+  const runId = normalizeString(value.run_id);
+  if (!stage && !status && !agent && !runId) return null;
+  return {
+    stage: WORKFLOW_STAGES.includes(stage) ? stage : null,
+    status: WORKFLOW_STATUSES.includes(status) ? status : 'idle',
+    agent,
+    run_id: runId,
+    started_at: normalizeString(value.started_at) || undefined,
+    finished_at: normalizeString(value.finished_at) || undefined
+  };
+}
+
+function normalizeAdr(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item, idx) => ({
+      id: normalizeString(item && item.id, `adr-${idx + 1}`),
+      decision: normalizeString(item && item.decision),
+      why: normalizeString(item && item.why),
+      created: normalizeString(item && item.created) || todayIso()
+    }))
+    .filter((item) => item.decision && item.why);
+}
+
+function nextAdrId(existing) {
+  let max = 0;
+  for (const item of existing) {
+    const match = normalizeString(item && item.id).match(/^adr-(\d+)$/i);
+    if (match) max = Math.max(max, parseInt(match[1], 10));
+  }
+  return `adr-${max + 1}`;
+}
+
+function appendAdrEntry(existing, entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw createKanbanError(
+      'VALIDATION_ERROR',
+      'adr must be an object with decision and why, or an array of such objects',
+      'Send adr: { decision: "...", why: "..." } to append one entry',
+      { field: 'adr' },
+      false,
+      400
+    );
+  }
+  const decision = normalizeString(entry.decision);
+  const why = normalizeString(entry.why);
+  if (!decision || !why) {
+    throw createKanbanError(
+      'VALIDATION_ERROR',
+      'adr.decision and adr.why must be non-empty strings',
+      'Provide both decision and why when appending an ADR',
+      { field: 'adr' },
+      false,
+      400
+    );
+  }
+  const list = normalizeAdr(existing);
+  list.push({
+    id: nextAdrId(list),
+    decision,
+    why,
+    created: normalizeString(entry.created) || todayIso()
+  });
+  return list;
 }
 
 function normalizePlan(value) {
@@ -291,9 +396,11 @@ function normalizeTask(task) {
     acceptance_criteria: normalizeStringArray(task.acceptance_criteria),
     test_cases: normalizeStringArray(task.test_cases),
     subtasks: normalizeSubtasks(task.subtasks),
+    adr: normalizeAdr(task.adr),
     notes: normalizeString(task.notes),
     plan: normalizePlan(task.plan),
     evidence: normalizeEvidence(task.evidence),
+    workflow: normalizeWorkflow(task.workflow),
     task_number: extractTaskNumber(id)
   };
 
@@ -316,9 +423,11 @@ function serializeTask(task) {
     acceptance_criteria: normalized.acceptance_criteria,
     test_cases: normalized.test_cases,
     subtasks: normalized.subtasks,
+    adr: normalized.adr,
     notes: normalized.notes,
     plan: normalized.plan,
     evidence: normalized.evidence,
+    workflow: normalized.workflow,
     task_number: normalized.task_number
   };
 }
@@ -356,7 +465,9 @@ function serializeEpic(epic) {
 function deriveEpicStatus(tasks, epic) {
   if (epic && epic.archived) return 'archived';
   if (!tasks || tasks.length === 0) return 'empty';
-  if (tasks.some((task) => task.column === 'active')) return 'active';
+  if (tasks.some((task) => WORKFLOW_STAGES.includes(task.column) || task.column === 'active')) {
+    return 'active';
+  }
   if (tasks.every((task) => task.column === 'done')) return 'done';
   return 'planned';
 }
@@ -374,13 +485,21 @@ function getEpicProgress(tasks) {
     tasks_done: 0,
     tasks_active: 0,
     tasks_planned: 0,
-    tasks_icebox: 0
+    tasks_icebox: 0,
+    tasks_testing: 0,
+    tasks_review: 0
+  };
+  const keyByCol = {
+    done: 'tasks_done',
+    active: 'tasks_active',
+    planned: 'tasks_planned',
+    icebox: 'tasks_icebox',
+    testing: 'tasks_testing',
+    review: 'tasks_review'
   };
   for (const task of tasks) {
-    if (task.column === 'done') progress.tasks_done += 1;
-    else if (task.column === 'active') progress.tasks_active += 1;
-    else if (task.column === 'planned') progress.tasks_planned += 1;
-    else if (task.column === 'icebox') progress.tasks_icebox += 1;
+    const key = keyByCol[task.column];
+    if (key) progress[key] += 1;
   }
   return progress;
 }
@@ -395,6 +514,24 @@ function pickEpicFields(epicPayload, fieldNames) {
   return picked;
 }
 
+function collectEpicAdrs(childTasks) {
+  const adrs = [];
+  for (const task of childTasks) {
+    const entries = normalizeAdr(task.adr);
+    for (const entry of entries) {
+      adrs.push({
+        task_id: task.id,
+        task_title: task.title,
+        id: entry.id,
+        decision: entry.decision,
+        why: entry.why,
+        created: entry.created
+      });
+    }
+  }
+  return adrs;
+}
+
 function shapeEpic(epic, tasks = [], options = {}) {
   const normalized = normalizeEpic(epic);
   const childTasks = tasks.filter((task) => task.epic_id === normalized.id);
@@ -402,7 +539,8 @@ function shapeEpic(epic, tasks = [], options = {}) {
     ...normalized,
     status: deriveEpicStatus(childTasks, normalized),
     progress: getEpicProgress(childTasks),
-    tasks: childTasks.map((task) => shapeTask(task, { view: 'summary' }))
+    tasks: childTasks.map((task) => shapeTask(task, { view: 'summary' })),
+    adrs: collectEpicAdrs(childTasks)
   };
   const fields = Array.isArray(options.fields) && options.fields.length > 0
     ? options.fields
@@ -479,6 +617,14 @@ function getProgress(task) {
   return { done, total };
 }
 
+function resolveEpicGoals(task, epicLookup) {
+  if (!task.epic_id) return '';
+  if (!epicLookup || typeof epicLookup !== 'object') return '';
+  const epic = epicLookup[task.epic_id];
+  if (!epic) return '';
+  return normalizeString(epic.goals);
+}
+
 function pickFields(task, fieldNames) {
   const picked = {};
 
@@ -487,6 +633,10 @@ function pickFields(task, fieldNames) {
       picked.progress = getProgress(task);
       continue;
     }
+    if (field === 'epic_goals') {
+      picked.epic_goals = task.epic_goals;
+      continue;
+    }
     if (field in task) {
       picked[field] = task[field];
     }
@@ -501,7 +651,11 @@ function shapeTask(task, options = {}) {
     ? options.fields
     : (VIEW_FIELDS[options.view || 'full'] || VIEW_FIELDS.full);
 
-  return pickFields(normalized, fields);
+  const withGoals = {
+    ...normalized,
+    epic_goals: resolveEpicGoals(normalized, options.epicLookup)
+  };
+  return pickFields(withGoals, fields);
 }
 
 function escapeRegex(value) {
@@ -1263,6 +1417,32 @@ function validateColumn(column, fieldName = 'column') {
   }
 }
 
+function allowedColumnsFrom(fromColumn) {
+  return COLUMN_TRANSITIONS[fromColumn] ? COLUMN_TRANSITIONS[fromColumn].slice() : [];
+}
+
+function validateTransition(fromColumn, toColumn, taskId) {
+  if (fromColumn === toColumn) return;
+  validateColumn(toColumn);
+  const allowed = allowedColumnsFrom(fromColumn);
+  if (allowed.includes(toColumn)) return;
+  throw createKanbanError(
+    'INVALID_TRANSITION',
+    taskId
+      ? `Cannot move task ${taskId} from ${fromColumn} to ${toColumn}`
+      : `Cannot move from ${fromColumn} to ${toColumn}`,
+    `From ${fromColumn} you can move only to: ${allowed.join(', ') || '(none)'}`,
+    {
+      task_id: taskId || undefined,
+      from: fromColumn,
+      to: toColumn,
+      allowed_columns: allowed
+    },
+    false,
+    400
+  );
+}
+
 function validatePatch(patch) {
   if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
     throw createKanbanError(
@@ -1316,6 +1496,7 @@ async function doCreate(title, column = 'planned', epicRef = '—', extra = {})
         subtasks: extra.subtasks,
         notes: extra.notes,
         plan: extra.plan,
+        adr: extra.adr,
         evidence: extra.evidence
       });
       try {
@@ -1354,6 +1535,9 @@ async function updateTaskRecord(taskId, patch) {
 
   if (patch.column !== undefined) {
     validateColumn(patch.column);
+    if (patch.column !== current.column) {
+      validateTransition(current.column, patch.column, current.id);
+    }
     next.column = patch.column;
   }
   if (patch.title !== undefined) {
@@ -1460,8 +1644,31 @@ async function updateTaskRecord(taskId, patch) {
     }
     next.subtasks = patch.subtasks;
   }
+  if (patch.adr !== undefined) {
+    if (Array.isArray(patch.adr)) {
+      next.adr = normalizeAdr(patch.adr);
+    } else {
+      next.adr = appendAdrEntry(next.adr, patch.adr);
+    }
+  }
   if (patch.notes !== undefined) next.notes = normalizeString(patch.notes);
   if (patch.plan !== undefined) next.plan = patch.plan;
+  if (patch.workflow !== undefined) {
+    next.workflow = patch.workflow === null ? null : normalizeWorkflow(patch.workflow);
+  }
+  if (patch.appendEvidence !== undefined) {
+    if (!patch.appendEvidence || typeof patch.appendEvidence !== 'object' || Array.isArray(patch.appendEvidence)) {
+      throw createKanbanError(
+        'VALIDATION_ERROR',
+        'appendEvidence must be an evidence object',
+        'Send a single evidence entry to append',
+        { field: 'appendEvidence' },
+        false,
+        400
+      );
+    }
+    next.evidence = [...normalizeEvidence(next.evidence), ...normalizeEvidence([patch.appendEvidence])];
+  }
   if (patch.evidence !== undefined) {
     if (!Array.isArray(patch.evidence)) {
       throw createKanbanError(
@@ -1479,9 +1686,36 @@ async function updateTaskRecord(taskId, patch) {
   return writeTask(next, previousFilePath);
 }
 
+function scheduleWorkflowEnqueue(previousColumn, updated) {
+  if (!updated || !WORKFLOW_STAGES.includes(updated.column)) return;
+  if (previousColumn === updated.column) return;
+  // Lazy require avoids circular load: workflow.js requires kanban.js.
+  setImmediate(() => {
+    try {
+      const workflow = require('./workflow.js');
+      Promise.resolve(workflow.maybeEnqueueOnColumnEnter(updated, previousColumn)).catch((err) => {
+        console.error('workflow enqueue failed:', err && err.message ? err.message : err);
+      });
+    } catch (err) {
+      console.error('workflow load failed:', err && err.message ? err.message : err);
+    }
+  });
+}
+
 async function updateTask(taskId, patch) {
   validatePatch(patch);
-  return withBoardLock(() => updateTaskRecord(taskId, patch));
+  let previousColumn = null;
+  const updated = await withBoardLock(async () => {
+    const resolvedId = await resolveTaskId(taskId);
+    const previousFilePath = await findFile(resolvedId);
+    if (previousFilePath) {
+      const current = await parseEpic(previousFilePath, path.basename(path.dirname(previousFilePath)));
+      previousColumn = current.column;
+    }
+    return updateTaskRecord(taskId, patch);
+  });
+  scheduleWorkflowEnqueue(previousColumn, updated);
+  return updated;
 }
 
 async function doMove(epicId, target) {
@@ -1489,7 +1723,7 @@ async function doMove(epicId, target) {
     await updateTask(epicId, { column: target });
     return true;
   } catch (error) {
-    if (error.code === 'TASK_NOT_FOUND' || error.code === 'INVALID_COLUMN') {
+    if (error.code === 'TASK_NOT_FOUND' || error.code === 'INVALID_COLUMN' || error.code === 'INVALID_TRANSITION') {
       return false;
     }
     throw error;
@@ -1579,8 +1813,14 @@ module.exports = {
   resolveTaskId,
   COLS,
   STATUS_MAP,
+  WORKFLOW_STAGES,
+  COLUMN_TRANSITIONS,
+  allowedColumnsFrom,
+  validateTransition,
   VIEW_FIELDS,
   EPIC_VIEW_FIELDS,
+  normalizeEvidence,
+  normalizeWorkflow,
   LIVE_EPIC_STATUSES,
   RECOMMENDED_CREATE_FIELDS,
   RECOMMENDED_EPIC_CREATE_FIELDS,

package/mcp-server.js

@@ -141,9 +141,22 @@ function normalizeReadOptions(args, defaultView) {
   return { view };
 }
 
-function formatTaskResult(task, returnShape) {
+async function buildEpicLookup() {
+  const epics = await kanban.listEpicEntities();
+  const lookup = {};
+  for (const epic of epics) {
+    lookup[epic.id] = epic;
+  }
+  return lookup;
+}
+
+async function formatTaskResult(task, returnShape) {
   if (returnShape === 'none') return { ok: true };
-  return kanban.shapeTask(task, { view: returnShape === 'full' ? 'full' : 'summary' });
+  const epicLookup = await buildEpicLookup();
+  return kanban.shapeTask(task, {
+    view: returnShape === 'full' ? 'full' : 'summary',
+    epicLookup
+  });
 }
 
 function guiIdentity(extra = {}) {
@@ -456,6 +469,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Freeform notes'
             },
+            adr: {
+              description:
+                'Append one ADR: { decision, why }. Or replace full array of { id?, decision, why, created? }.',
+              oneOf: [
+                {
+                  type: 'object',
+                  properties: {
+                    decision: { type: 'string' },
+                    why: { type: 'string' }
+                  },
+                  required: ['decision', 'why']
+                },
+                {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      id: { type: 'string' },
+                      decision: { type: 'string' },
+                      why: { type: 'string' },
+                      created: { type: 'string' }
+                    }
+                  }
+                }
+              ]
+            },
             task_id: {
               type: 'string',
               description: "Required for move/update/delete/plan_* except plan_create. '014' or '14'."
@@ -463,7 +502,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             column: {
               type: 'string',
               enum: COLS,
-              description: 'Target column for move (not col)'
+              description:
+                'Target column for move (not col). Must be a legal transition from the current column. '
+                + 'icebox→planned; planned→active|icebox|testing; active→planned|testing|icebox; '
+                + 'testing→active|review; review→active|done; done→active. Illegal → INVALID_TRANSITION + allowed_columns.'
             },
             patch: {
               type: 'object',
@@ -571,6 +613,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             });
           }
 
+          // summary omits epic_goals; no lookup needed for list tokens
           result = tasks.map((task) => kanban.shapeTask(task, readOptions));
         } else if (operation === 'show') {
           if (!args.task_id) {
@@ -581,7 +624,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             );
           }
 
-          result = kanban.shapeTask(await kanban.getTask(args.task_id), readOptions);
+          await kanban.migrateEpicGroups();
+          const epicLookup = await buildEpicLookup();
+          result = kanban.shapeTask(await kanban.getTask(args.task_id), {
+            ...readOptions,
+            epicLookup
+          });
         } else if (operation === 'list_epics') {
           await kanban.migrateEpicGroups();
           const tasks = await kanban.allTasks();
@@ -643,7 +691,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
             const epicRef = args.epic_id || args.epic || '—';
             const created = await kanban.doCreate(args.title, args.col || 'planned', epicRef, createPayload);
-            const shaped = kanban.shapeTask(created, { view: 'full' });
+            const shaped = kanban.shapeTask(created, {
+              view: 'full',
+              epicLookup: await buildEpicLookup()
+            });
             const warnings = kanban.createFieldWarnings(createPayload);
             result = warnings.length > 0
               ? { ...shaped, warnings, missing_recommended: kanban.missingRecommendedCreateFields(createPayload) }
@@ -769,7 +820,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               );
             }
             const updated = await kanban.updateTask(args.task_id, { column: args.column });
-            result = formatTaskResult(updated, returnShape);
+            result = await formatTaskResult(updated, returnShape);
             break;
           }
 
@@ -791,11 +842,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             if (args.test_cases !== undefined) patch.test_cases = args.test_cases;
             if (args.subtasks !== undefined) patch.subtasks = args.subtasks;
             if (args.notes !== undefined) patch.notes = args.notes;
+            if (args.adr !== undefined) patch.adr = args.adr;
             if (args.epic_id !== undefined) patch.epic_id = args.epic_id;
             else if (args.epic !== undefined) patch.epic = args.epic;
             if (args.col !== undefined) patch.column = args.col;
             const updated = await kanban.updateTask(args.task_id, patch);
-            result = formatTaskResult(updated, returnShape);
+            result = await formatTaskResult(updated, returnShape);
             break;
           }
 
@@ -892,8 +944,8 @@ function installGuiShutdownHooks() {
     if (!ownsGuiProcess()) return;
     try {
       await stopGuiServer();
-    } catch {
-      // best-effort
+    } catch (error) {
+      console.error(`kanbango GUI shutdown failed: ${error.message}`);
     }
   }
 
@@ -901,8 +953,8 @@ function installGuiShutdownHooks() {
     if (ownsGuiProcess()) {
       try {
         guiProcess.kill();
-      } catch {
-        // ignore
+      } catch (error) {
+        console.error(`kanbango GUI kill on exit failed: ${error.message}`);
       }
     }
   });

package/package.json

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

package/plan.js

@@ -147,8 +147,11 @@ async function done(payload = {}) {
     throw planError('PLAN_INCOMPLETE', 'Plan has incomplete subtasks',
       'Advance every plan step before marking the workflow done', { incomplete });
   }
-  const updated = await kanban.updateTask(task.id, { column: 'done', plan: { ...task.plan, status: 'done' } });
-  return result(updated, { status: 'done' });
+  const updated = await kanban.updateTask(task.id, {
+    column: 'testing',
+    plan: { ...(task.plan || {}), status: 'done' }
+  });
+  return result(updated, { status: 'done', column: updated.column });
 }
 
 async function status(taskId) {