kanbango 3.6.2 → 3.8.0

package/kanban.js

@@ -3,7 +3,10 @@ const path = require('path');
 
 const BACKLOG = path.join(process.cwd(), 'backlog');
 const EPICS_DIR = path.join(BACKLOG, 'epics');
-const COLS = ['active', 'planned', 'icebox', 'testing', 'review', 'done'];
+/** All physical column dirs that may exist on disk (including disabled gates). */
+const KNOWN_COLS = ['active', 'planned', 'icebox', 'testing', 'review', 'done'];
+/** Active columns for validation / MCP / create — mutated by applyBoardLayout. */
+let COLS = KNOWN_COLS.slice();
 const STATUS_MAP = {
   active: 'in_progress',
   planned: 'planned',
@@ -12,11 +15,12 @@ const STATUS_MAP = {
   review: 'review',
   done: 'done'
 };
-const WORKFLOW_STAGES = ['testing', 'review'];
+/** Gate stages that may spawn agents — subset of active COLS. */
+let 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 = {
+// Agent/human move contract. Same column is always a no-op. Mutated by applyBoardLayout.
+let COLUMN_TRANSITIONS = {
   icebox: ['planned'],
   planned: ['active', 'icebox', 'testing'],
   active: ['planned', 'testing', 'icebox'],
@@ -24,8 +28,31 @@ const COLUMN_TRANSITIONS = {
   review: ['active', 'done'],
   done: ['active']
 };
+
+/**
+ * Apply project board layout from backlog/kanbango.json (via workflow.ensureBoardConfig).
+ * Does not create/delete dirs; only changes which columns are legal and which transitions apply.
+ */
+function applyBoardLayout({ cols, transitions, workflowStages } = {}) {
+  if (Array.isArray(cols) && cols.length > 0) {
+    COLS = cols.slice();
+  }
+  if (transitions && typeof transitions === 'object' && !Array.isArray(transitions)) {
+    COLUMN_TRANSITIONS = {};
+    for (const [from, targets] of Object.entries(transitions)) {
+      COLUMN_TRANSITIONS[from] = Array.isArray(targets) ? targets.slice() : [];
+    }
+  }
+  if (Array.isArray(workflowStages)) {
+    WORKFLOW_STAGES = workflowStages.slice();
+  }
+  // Keep module.exports live references in sync for consumers that cached the export object.
+  module.exports.COLS = COLS;
+  module.exports.COLUMN_TRANSITIONS = COLUMN_TRANSITIONS;
+  module.exports.WORKFLOW_STAGES = WORKFLOW_STAGES;
+}
 const VIEW_FIELDS = {
-  summary: ['task_number', 'title', 'column', 'epic_id', 'epic_group', 'created', 'progress'],
+  summary: ['task_number', 'title', 'column', 'epic_id', 'epic_group', 'created', 'progress', 'blocked'],
   planning: [
     'task_number',
     'title',
@@ -40,7 +67,11 @@ const VIEW_FIELDS = {
     'in_scope',
     'out_of_scope',
     'acceptance_criteria',
-    'test_cases'
+    'test_cases',
+    'depends_on',
+    'blocked',
+    'unmet_dependencies',
+    'blocks'
   ],
   execution: [
     'task_number',
@@ -61,7 +92,12 @@ const VIEW_FIELDS = {
     'adr',
     'evidence',
     'plan',
-    'workflow'
+    'workflow',
+    'depends_on',
+    'files',
+    'blocked',
+    'unmet_dependencies',
+    'blocks'
   ],
   full: [
     'task_number',
@@ -83,7 +119,12 @@ const VIEW_FIELDS = {
     'notes',
     'evidence',
     'plan',
-    'workflow'
+    'workflow',
+    'depends_on',
+    'files',
+    'blocked',
+    'unmet_dependencies',
+    'blocks'
   ]
 };
 
@@ -208,6 +249,173 @@ function normalizeStringArray(value) {
     .filter(Boolean);
 }
 
+function normalizeTaskIdRef(value) {
+  const raw = normalizeString(value);
+  if (!raw) return '';
+  if (/^\d+$/.test(raw)) return raw.padStart(3, '0');
+  return raw;
+}
+
+function uniqueNormalizedStrings(value, mapItem) {
+  if (!Array.isArray(value)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const item of value) {
+    const next = mapItem(item);
+    if (!next || seen.has(next)) continue;
+    seen.add(next);
+    out.push(next);
+  }
+  return out;
+}
+
+function normalizeDependsOn(value) {
+  return uniqueNormalizedStrings(value, normalizeTaskIdRef);
+}
+
+function normalizeFiles(value) {
+  return uniqueNormalizedStrings(value, normalizeString);
+}
+
+function isWorkColumn(column) {
+  return column === 'active' || WORKFLOW_STAGES.includes(column);
+}
+
+function unmetDependencies(task, allTasks) {
+  const deps = Array.isArray(task && task.depends_on) ? task.depends_on : [];
+  if (deps.length === 0) return [];
+  const byId = new Map();
+  for (const other of allTasks || []) {
+    byId.set(other.id, other);
+  }
+  const unmet = [];
+  for (const depId of deps) {
+    const dep = byId.get(depId);
+    if (!dep || dep.column !== 'done') {
+      unmet.push({
+        id: depId,
+        column: dep ? dep.column : null,
+        missing: !dep
+      });
+    }
+  }
+  return unmet;
+}
+
+function assertUnblockedForColumn(task, targetColumn, allTasks) {
+  if (!isWorkColumn(targetColumn)) return;
+  const unmet = unmetDependencies(task, allTasks);
+  if (unmet.length === 0) return;
+  const labels = unmet.map((item) => (
+    item.missing ? `${item.id} (missing)` : `${item.id} (${item.column})`
+  ));
+  throw createKanbanError(
+    'TASK_BLOCKED',
+    `Task ${task.id} is blocked by incomplete tasks: ${labels.join(', ')}`,
+    'Finish dependency tasks (move them to done) or remove them from depends_on',
+    {
+      task_id: task.id,
+      unmet_dependencies: unmet.map((item) => item.id),
+      blocked_by: unmet
+    },
+    false,
+    400
+  );
+}
+
+function computeBlocks(taskId, allTasks) {
+  if (!taskId) return [];
+  return (allTasks || [])
+    .filter((other) => other.id !== taskId && (other.depends_on || []).includes(taskId))
+    .map((other) => other.id)
+    .sort();
+}
+
+function findDependencyCycle(taskId, dependsOn, allTasks) {
+  const graph = new Map();
+  for (const other of allTasks || []) {
+    graph.set(other.id, (other.depends_on || []).slice());
+  }
+  graph.set(taskId, Array.isArray(dependsOn) ? dependsOn.slice() : []);
+
+  const visiting = new Set();
+  const visited = new Set();
+  const stack = [];
+
+  function dfs(id) {
+    if (visiting.has(id)) {
+      const start = stack.indexOf(id);
+      return stack.slice(start).concat(id);
+    }
+    if (visited.has(id)) return null;
+    visiting.add(id);
+    stack.push(id);
+    for (const depId of graph.get(id) || []) {
+      const cycle = dfs(depId);
+      if (cycle) return cycle;
+    }
+    stack.pop();
+    visiting.delete(id);
+    visited.add(id);
+    return null;
+  }
+
+  return dfs(taskId);
+}
+
+function assertNoDependencyCycle(taskId, dependsOn, allTasks) {
+  const cycle = findDependencyCycle(taskId, dependsOn, allTasks);
+  if (!cycle) return;
+  throw createKanbanError(
+    'CIRCULAR_DEPENDENCY',
+    `Circular dependency: ${cycle.join(' → ')}`,
+    'Remove one of the depends_on links that closes the loop',
+    { cycle },
+    false,
+    400
+  );
+}
+
+function newlyUnblockedTasks(doneTaskId, allTasks) {
+  return (allTasks || [])
+    .filter((other) => other.id !== doneTaskId && (other.depends_on || []).includes(doneTaskId))
+    .filter((other) => unmetDependencies(other, allTasks).length === 0)
+    .map((other) => other.id)
+    .sort();
+}
+
+function firstEnabledGateColumn() {
+  if (COLS.includes('testing')) return 'testing';
+  if (COLS.includes('review')) return 'review';
+  return 'done';
+}
+
+function nextMoveAction() {
+  const gate = firstEnabledGateColumn();
+  if (gate === 'testing') return 'move_testing';
+  if (gate === 'review') return 'move_review';
+  return 'move_done';
+}
+
+function resolveNextAction(task, mode) {
+  if (mode === 'start') return 'start';
+  if (mode === 'idle') return 'idle';
+  const status = task.workflow && task.workflow.status;
+  if (
+    (task.column === 'testing' || task.column === 'review')
+    && (status === 'fail' || status === 'blocked')
+  ) {
+    return 'fix_gate';
+  }
+  if (currentSubtask(task)) return 'advance';
+  const evidence = Array.isArray(task.evidence) ? task.evidence : [];
+  if (evidence.length === 0) return 'evidence';
+  if (task.column === 'active') return nextMoveAction();
+  if (task.column === 'testing' && COLS.includes('review')) return 'move_review';
+  if (task.column === 'testing' || task.column === 'review') return 'move_done';
+  return 'implement';
+}
+
 function isPresentCreateField(field, value) {
   if (
     field === 'description'
@@ -385,7 +593,8 @@ function normalizeTask(task) {
   const normalized = {
     id,
     title: stripTitlePrefix(task.title || id),
-    column: COLS.includes(task.column) ? task.column : 'planned',
+    // Accept any known physical column so disabled-gate cards stay readable until migrated.
+    column: KNOWN_COLS.includes(task.column) ? task.column : 'planned',
     epic_id: epicId,
     epic_group: epicId ? (epicGroup === '—' ? epicId : epicGroup) : (epicGroup === '—' ? '—' : epicGroup),
     created: normalizeString(task.created) || todayIso(),
@@ -401,6 +610,8 @@ function normalizeTask(task) {
     plan: normalizePlan(task.plan),
     evidence: normalizeEvidence(task.evidence),
     workflow: normalizeWorkflow(task.workflow),
+    depends_on: normalizeDependsOn(task.depends_on).filter((depId) => depId !== id),
+    files: normalizeFiles(task.files),
     task_number: extractTaskNumber(id)
   };
 
@@ -428,6 +639,8 @@ function serializeTask(task) {
     plan: normalized.plan,
     evidence: normalized.evidence,
     workflow: normalized.workflow,
+    depends_on: normalized.depends_on,
+    files: normalized.files,
     task_number: normalized.task_number
   };
 }
@@ -539,7 +752,7 @@ 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', allTasks: tasks })),
     adrs: collectEpicAdrs(childTasks)
   };
   const fields = Array.isArray(options.fields) && options.fields.length > 0
@@ -617,6 +830,66 @@ function getProgress(task) {
   return { done, total };
 }
 
+function currentSubtask(task) {
+  const subtasks = Array.isArray(task && task.subtasks) ? task.subtasks : [];
+  const open = subtasks.find((subtask) => !subtask.done);
+  if (!open) return null;
+  return { id: open.id, text: open.text };
+}
+
+function compactContextTask(task, allTasks, epicLookup, mode) {
+  const unmet = unmetDependencies(task, allTasks);
+  const subtask = currentSubtask(task);
+  return {
+    mode,
+    next_action: resolveNextAction(task, mode),
+    task_id: task.id,
+    title: task.title,
+    column: task.column,
+    epic_id: task.epic_id,
+    epic_goals: resolveEpicGoals(task, epicLookup),
+    current_subtask: subtask,
+    progress: getProgress(task),
+    files: task.files || [],
+    blocked: unmet.length > 0,
+    unmet_dependencies: unmet.map((item) => item.id),
+    blocks: computeBlocks(task.id, allTasks)
+  };
+}
+
+async function getContextPayload(options = {}) {
+  const tasks = await allTasks();
+  const epics = await listEpicEntities();
+  const epicLookup = {};
+  for (const epic of epics) {
+    epicLookup[epic.id] = epic;
+  }
+  let liveTasks = filterTasksForList(tasks, epics, {});
+  const epicFilter = options.epic_id || options.epic;
+  if (epicFilter) {
+    liveTasks = liveTasks.filter((task) => taskMatchesEpicFilter(task, epicFilter));
+  }
+  const active = liveTasks.find((task) => task.column === 'active');
+  if (active) {
+    return compactContextTask(active, tasks, epicLookup, 'continue');
+  }
+  const gateFix = liveTasks.find((task) => {
+    const status = task.workflow && task.workflow.status;
+    return (task.column === 'testing' || task.column === 'review')
+      && (status === 'fail' || status === 'blocked');
+  });
+  if (gateFix) {
+    return compactContextTask(gateFix, tasks, epicLookup, 'continue');
+  }
+  const ready = liveTasks
+    .filter((task) => task.column === 'planned' && unmetDependencies(task, tasks).length === 0)
+    .sort((a, b) => (a.task_number || 0) - (b.task_number || 0));
+  if (ready.length > 0) {
+    return compactContextTask(ready[0], tasks, epicLookup, 'start');
+  }
+  return { mode: 'idle', next_action: 'idle' };
+}
+
 function resolveEpicGoals(task, epicLookup) {
   if (!task.epic_id) return '';
   if (!epicLookup || typeof epicLookup !== 'object') return '';
@@ -650,10 +923,15 @@ function shapeTask(task, options = {}) {
   const fields = Array.isArray(options.fields) && options.fields.length > 0
     ? options.fields
     : (VIEW_FIELDS[options.view || 'full'] || VIEW_FIELDS.full);
+  const allTasks = options.allTasks;
+  const unmet = allTasks ? unmetDependencies(normalized, allTasks) : [];
 
   const withGoals = {
     ...normalized,
-    epic_goals: resolveEpicGoals(normalized, options.epicLookup)
+    epic_goals: resolveEpicGoals(normalized, options.epicLookup),
+    blocked: unmet.length > 0,
+    unmet_dependencies: unmet.map((item) => item.id),
+    blocks: allTasks ? computeBlocks(normalized.id, allTasks) : []
   };
   return pickFields(withGoals, fields);
 }
@@ -684,7 +962,8 @@ function parseListSection(sectionText) {
 }
 
 async function ensureBacklogDir() {
-  for (const col of COLS) {
+  // Always create the full known set so disabled gates can still hold legacy files until migrated.
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     await fs.mkdir(colDir, { recursive: true });
   }
@@ -773,7 +1052,7 @@ async function parseEpic(filePath, column) {
 async function allEpics() {
   const epics = [];
 
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1232,7 +1511,7 @@ function taskMatchesEpicFilter(task, epicFilter) {
 }
 
 async function findFile(epicId) {
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1277,7 +1556,7 @@ async function resolveTaskId(input) {
   const num = parseInt(String(input), 10);
   if (!Number.isFinite(num)) return null;
 
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1298,7 +1577,7 @@ async function resolveTaskId(input) {
 
 async function removeOtherTaskCopies(taskId, keepPath) {
   const keep = path.resolve(keepPath);
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1341,7 +1620,7 @@ async function migrateAll(options = {}) {
   const migrated = [];
   const errors = [];
 
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     let files;
     try {
@@ -1387,7 +1666,7 @@ async function migrateAll(options = {}) {
 async function nextTaskNumber() {
   const ids = [];
 
-  for (const col of COLS) {
+  for (const col of KNOWN_COLS) {
     const colDir = path.join(BACKLOG, col);
     try {
       const files = await fs.readdir(colDir);
@@ -1421,6 +1700,71 @@ function allowedColumnsFrom(fromColumn) {
   return COLUMN_TRANSITIONS[fromColumn] ? COLUMN_TRANSITIONS[fromColumn].slice() : [];
 }
 
+/** List tasks sitting in a known physical column dir (even if that column is disabled). */
+async function listTasksInKnownColumn(column) {
+  if (!KNOWN_COLS.includes(column)) {
+    throw createKanbanError(
+      'INVALID_COLUMN',
+      `Column ${column} is not valid`,
+      `Use one of: ${KNOWN_COLS.join(', ')}`,
+      { column, valid_columns: KNOWN_COLS },
+      false,
+      400
+    );
+  }
+  const colDir = path.join(BACKLOG, column);
+  const tasks = [];
+  try {
+    const files = await fs.readdir(colDir);
+    for (const file of files) {
+      if (!isTaskOrEpicDataFile(file)) continue;
+      try {
+        tasks.push(await parseEpic(path.join(colDir, file), column));
+      } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        throw error;
+      }
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return tasks;
+}
+
+/**
+ * Force-move a task to a column without transition checks (config migration only).
+ * Still validates target is a known column and uses writeTask + board lock.
+ */
+async function relocateTask(taskId, targetColumn) {
+  if (!KNOWN_COLS.includes(targetColumn)) {
+    throw createKanbanError(
+      'INVALID_COLUMN',
+      `Column ${targetColumn} is not valid`,
+      `Use one of: ${KNOWN_COLS.join(', ')}`,
+      { column: targetColumn, valid_columns: KNOWN_COLS },
+      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)));
+    if (current.column === targetColumn) return current;
+    return writeTask({ ...current, column: targetColumn }, previousFilePath);
+  });
+}
+
 function validateTransition(fromColumn, toColumn, taskId) {
   if (fromColumn === toColumn) return;
   validateColumn(toColumn);
@@ -1497,8 +1841,15 @@ async function doCreate(title, column = 'planned', epicRef = '—', extra = {})
         notes: extra.notes,
         plan: extra.plan,
         adr: extra.adr,
-        evidence: extra.evidence
+        evidence: extra.evidence,
+        depends_on: extra.depends_on,
+        files: extra.files
       });
+      const existing = await allTasks();
+      assertNoDependencyCycle(task.id, normalizeDependsOn(extra.depends_on), existing);
+      if (isWorkColumn(task.column)) {
+        assertUnblockedForColumn(task, task.column, existing);
+      }
       try {
         return await writeTask(task, null, { exclusive: true });
       } catch (error) {
@@ -1540,6 +1891,32 @@ async function updateTaskRecord(taskId, patch) {
     }
     next.column = patch.column;
   }
+  if (patch.depends_on !== undefined) {
+    if (!Array.isArray(patch.depends_on)) {
+      throw createKanbanError(
+        'VALIDATION_ERROR',
+        'depends_on must be an array of task ids',
+        'Send depends_on as an array like ["001"]',
+        { field: 'depends_on' },
+        false,
+        400
+      );
+    }
+    next.depends_on = patch.depends_on;
+  }
+  if (patch.files !== undefined) {
+    if (!Array.isArray(patch.files)) {
+      throw createKanbanError(
+        'VALIDATION_ERROR',
+        'files must be an array of paths',
+        'Send files as an array like ["src/foo.js"]',
+        { field: 'files' },
+        false,
+        400
+      );
+    }
+    next.files = patch.files;
+  }
   if (patch.title !== undefined) {
     const title = normalizeString(patch.title);
     if (!title) {
@@ -1683,7 +2060,26 @@ async function updateTaskRecord(taskId, patch) {
     next.evidence = patch.evidence;
   }
 
-  return writeTask(next, previousFilePath);
+  const columnChanged = next.column !== current.column;
+  const depsChanged = patch.depends_on !== undefined;
+  const enteringDone = columnChanged && next.column === 'done';
+  let others = null;
+  if (depsChanged || (columnChanged && isWorkColumn(next.column)) || enteringDone) {
+    others = await allTasks();
+  }
+  if (depsChanged) {
+    assertNoDependencyCycle(current.id, normalizeDependsOn(next.depends_on), others);
+  }
+  if (columnChanged && isWorkColumn(next.column)) {
+    assertUnblockedForColumn(normalizeTask(next), next.column, others);
+  }
+
+  const written = await writeTask(next, previousFilePath);
+  if (enteringDone) {
+    const board = others.map((other) => (other.id === written.id ? written : other));
+    written.unblocked_tasks = newlyUnblockedTasks(written.id, board);
+  }
+  return written;
 }
 
 function scheduleWorkflowEnqueue(previousColumn, updated) {
@@ -1808,10 +2204,18 @@ module.exports = {
   missingRecommendedCreateFields,
   missingRecommendedEpicCreateFields,
   getProgress,
+  getContextPayload,
+  unmetDependencies,
+  computeBlocks,
+  newlyUnblockedTasks,
   getEpicProgress,
   deriveEpicStatus,
   resolveTaskId,
+  applyBoardLayout,
+  listTasksInKnownColumn,
+  relocateTask,
   COLS,
+  KNOWN_COLS,
   STATUS_MAP,
   WORKFLOW_STAGES,
   COLUMN_TRANSITIONS,
@@ -1826,3 +2230,8 @@ module.exports = {
   RECOMMENDED_EPIC_CREATE_FIELDS,
   EPICS_DIR
 };
+
+// Keep live refs for applyBoardLayout consumers that read module.exports.COLS
+module.exports.COLS = COLS;
+module.exports.COLUMN_TRANSITIONS = COLUMN_TRANSITIONS;
+module.exports.WORKFLOW_STAGES = WORKFLOW_STAGES;