kanbango 3.1.0 → 3.2.0

package/.ai/lessons.jsonl

@@ -2,3 +2,4 @@
 {"id":"260729-1ur","ts":"2026-07-29","scope":"proj","tags":["javascript","objects"],"rule":"DON'T Use empty object fallbacks in spreads like `...(obj || {})` since spreading falsy is safe","when":"object spread","sev":2,"hits":1}
 {"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}

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

@@ -1 +1 @@
-{"ts":"2026-07-29T10:38:42.184Z","sessionID":"ses_052c1be3fffeNPoV7VO6z40X2I","added":["260729-1ch"],"bumped":[]}
+{"ts":"2026-07-31T13:58:00.629Z","sessionID":"ses_04792cf77ffec14LhSNoSJReg9","added":["260731-o6g"],"bumped":[]}

package/AGENTS.md

@@ -8,11 +8,13 @@ Source of truth: `agent-playbook.js` (also MCP tool descriptions + `kanban_read`
 
 - hierarchy: epic (context) → task (work+plan) → subtasks (steps)
 - list: `col` filter, `view=summary`; keep `task_id`s; no full-board re-list after every write
-- list_epics / show_epic for initiatives; filter tasks with `epic=E001`
+- 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
 - 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: `return=none`; subtasks = full array replace (no toggle)
+- move/update/delete: `return=none`; subtasks = full array replace (no toggle)
+- cleanup: `delete` (task), `epic_delete` (cascade), `epic_archive` / `epic_unarchive`
 - non-trivial work: `plan_create` → `plan_advance` → `plan_evidence` (real tests, truncated logs) → `plan_done`
 - gui: `status` before `start`; `stop` only owned; `external_running` = do not kill
 

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to kanbango will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [3.2.0] - 2026-07-31
+
+### Added
+- GUI project label: browser tab title, header, port file, and `kanban_gui` start/status include `project` (basename of cwd; override with `KANBANGO_PROJECT_NAME`)
+- Epic field `archived` + status `archived` (overrides derived child rollup)
+- Hard delete: MCP `delete` / `epic_delete` (cascade child tasks), CLI `kanban rm` / `kanban epic rm`, HTTP `DELETE`
+- Archive: MCP `epic_archive` / `epic_unarchive`, CLI `kanban epic archive|unarchive`, HTTP `POST .../archive|unarchive`
+- `list_epics` default live-only (empty|planned|active); `include_archived`, `include_done`, `status` filters
+- Task `list` hides tasks under done/archived epics unless `include_archived`/`include_done` (explicit `epic=` filter still shows them)
+- GUI: Archive/Unarchive/Delete on epic swimlane, Delete on task card, Show archived toggle
+- Tests: `tests/delete-archive.test.js`
+
+### Changed
+- Agent playbook documents cleanup + live-only epic discovery
+- `show` / `show_epic` by id still return archived items (explicit lookup)
+
 ## [3.1.0] - 2026-07-30
 
 ### Added

package/LLM_AGENTS.md

@@ -249,7 +249,7 @@ Control the web GUI server: start, stop, or check status.
 2. Else `KANBANGO_GUI_PORT` env
 3. Else stable hash of project cwd in range `5510–5999`
 
-If the preferred port is busy, the server picks the next free port. Always trust the returned `url` / `port` (also written to `backlog/.kanbango-gui.json`).
+If the preferred port is busy, the server picks the next free port. Always trust the returned `url` / `port` (also written to `backlog/.kanbango-gui.json`). Responses also include `project` (basename of project cwd, or `KANBANGO_PROJECT_NAME`) so agents and humans can tell boards apart; the GUI tab title and header show the same label.
 
 **Auto-start with MCP:** set `KANBANGO_AUTO_GUI=1` in the MCP server env. GUI starts when MCP starts; use `status` to read the URL.
 

package/README.md

@@ -35,10 +35,17 @@ kanban list --json
 kanban epic add "Phase 1" --description "Why this initiative" --goals "Ship X"
 kanban add "My task" --col planned --epic E001
 
-# List epics / show epic with child rollup
+# List epics / show epic with child rollup (default: live only)
 kanban epic list --json
+kanban epic list --all --json
 kanban epic show E001
 
+# Archive or delete (epic_delete cascades child tasks)
+kanban epic archive E001
+kanban epic unarchive E001
+kanban epic rm E001
+kanban rm 001
+
 # Show details
 kanban show 001
 
@@ -130,7 +137,7 @@ Auto-start the web GUI with MCP (opt-in):
 }
 ```
 
-Optional: pin the port with `KANBANGO_GUI_PORT` (e.g. `"5821"`). Without it, each project gets a stable port in `5510–5999` derived from the project path. The real URL is always available via `kanban_gui` → `status` (and written to `backlog/.kanbango-gui.json` while the GUI runs).
+Optional: pin the port with `KANBANGO_GUI_PORT` (e.g. `"5821"`). Without it, each project gets a stable port in `5510–5999` derived from the project path. The real URL is always available via `kanban_gui` → `status` (and written to `backlog/.kanbango-gui.json` while the GUI runs). The browser tab title, GUI header, and `kanban_gui` responses include `project` (folder name of the project cwd; override with `KANBANGO_PROJECT_NAME`).
 
 Or generate the config files automatically:
 

package/agent-playbook.js

@@ -8,11 +8,13 @@ const DROP_IN_RULE = [
   'Kanbango MCP — token rules:',
   '- hierarchy: epic (context) → task (work+plan) → subtasks (steps)',
   '- list: col filter, view=summary; keep task_ids; no full-board re-list after writes',
-  '- list_epics / show_epic for initiatives; list tasks with epic=E001 for work',
+  '- 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',
   '- 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: return=none; subtasks=full array replace',
+  '- 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'
 ].join('\n');
@@ -22,7 +24,9 @@ const TOOL_DESCRIPTIONS = {
     '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.',
-    'list_epics/show_epic for initiatives; filter list with epic=E001 or epic title.',
+    '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.',
     'Do not re-list the whole board after every write — keep task_id from create/move.',
     'Task IDs numeric ("014"); epic IDs "E001". views: summary|planning|execution|full; fields[] overrides view.',
     'operation=help returns this playbook as short text (no board I/O).'
@@ -31,9 +35,11 @@ const TOOL_DESCRIPTIONS = {
   kanban_manage: [
     '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 (daily); epic_create|epic_update (containers);',
+    'Actions: create|move|update|delete (daily); epic_create|epic_update|epic_archive|epic_unarchive|epic_delete;',
     'plan_create→plan_advance→plan_evidence→plan_done (non-trivial only).',
     'epic_create: title + description/goals/in_scope/out_of_scope. Link tasks via epic=E001.',
+    'delete: task_id (hard remove). epic_delete: epic_id, always cascades child tasks.',
+    'epic_archive/epic_unarchive: epic_id — hide/restore initiative without deleting history.',
     'create/plan_create: title required; also send description,specs,in_scope,out_of_scope,acceptance_criteria',
     '(missing → warnings, not failure). move: task_id+column. update: task_id + fields or subtasks[] full list',
     '(no toggle). plan_evidence needs real test run: diff,test_command,stdout,stderr,exit_code — truncate logs.',
@@ -55,7 +61,9 @@ const MUST_CONTAIN = [
   'plan_create',
   'external_running',
   'subtasks',
-  'epic_create'
+  'epic_create',
+  'epic_archive',
+  'epic_delete'
 ];
 
 function playbookHelpPayload() {

package/bin/kanban.js

@@ -145,8 +145,9 @@ async function cliMcpInit(options) {
   }
 }
 
-async function cliList(colFilter, epicFilter, asJson) {
+async function cliList(colFilter, epicFilter, asJson, listOptions = {}) {
   await kanban.migrateEpicGroups();
+  const epics = await kanban.listEpicEntities();
   let tasks = await kanban.allTasks();
 
   if (colFilter) {
@@ -154,6 +155,8 @@ async function cliList(colFilter, epicFilter, asJson) {
   }
   if (epicFilter) {
     tasks = tasks.filter((task) => kanban.taskMatchesEpicFilter(task, epicFilter));
+  } else {
+    tasks = kanban.filterTasksForList(tasks, epics, listOptions);
   }
 
   if (asJson) {
@@ -207,11 +210,14 @@ async function cliShow(taskId) {
   }
 }
 
-async function cliEpicList(asJson) {
+async function cliEpicList(asJson, listOptions = {}) {
   await kanban.migrateEpicGroups();
   const tasks = await kanban.allTasks();
   const epics = await kanban.listEpicEntities();
-  const shaped = epics.map((epic) => kanban.shapeEpic(epic, tasks, { view: 'summary' }));
+  const shaped = kanban.filterShapedEpics(
+    epics.map((epic) => kanban.shapeEpic(epic, tasks, { view: 'summary' })),
+    listOptions
+  );
 
   if (asJson) {
     console.log(JSON.stringify(shaped, null, 2));
@@ -225,8 +231,9 @@ async function cliEpicList(asJson) {
 
   for (const epic of shaped) {
     const p = epic.progress || {};
+    const flag = epic.archived ? ' [archived]' : '';
     console.log(
-      `  ${epic.id.padEnd(6)}  ${epic.status.padEnd(8)}  ${String(epic.title).substring(0, 40).padEnd(40)}  ${p.tasks_done || 0}/${p.tasks_total || 0} tasks`
+      `  ${epic.id.padEnd(6)}  ${epic.status.padEnd(8)}  ${String(epic.title).substring(0, 40).padEnd(40)}  ${p.tasks_done || 0}/${p.tasks_total || 0} tasks${flag}`
     );
   }
 }
@@ -265,6 +272,38 @@ async function cliEpicUpdate(epicId, patch) {
   }
 }
 
+async function cliEpicArchive(epicId, archived) {
+  try {
+    const epic = archived
+      ? await kanban.archiveEpic(epicId)
+      : await kanban.unarchiveEpic(epicId);
+    console.log(`✓ Epic ${epic.id} ${archived ? 'archived' : 'unarchived'}`);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function cliEpicDelete(epicId) {
+  try {
+    const result = await kanban.deleteEpic(epicId);
+    console.log(`✓ Deleted epic ${result.epic_id} (+${result.deleted_task_count} tasks)`);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function cliDelete(taskId) {
+  try {
+    const result = await kanban.deleteTask(taskId);
+    console.log(`✓ Deleted task ${shortId(result.task_id)}: ${result.title}`);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    process.exit(1);
+  }
+}
+
 async function cliMove(taskId, column) {
   const success = await kanban.doMove(taskId, column);
   if (success) {
@@ -286,8 +325,21 @@ async function cliAdd(title, column, epicGroup) {
   }
 }
 
+function injectProjectIntoHtml(html, project) {
+  const safe = String(project)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+  return html
+    .replace(/<title>[^<]*<\/title>/, `<title>${safe} · Kanban</title>`)
+    .replace(/<h1>Donna Kanban<\/h1>/, `<h1>${safe}</h1>`);
+}
+
 async function serveWeb(port) {
-  const html = fs.readFileSync(path.join(__dirname, '..', 'index.html'), 'utf-8');
+  const htmlTemplate = fs.readFileSync(path.join(__dirname, '..', 'index.html'), 'utf-8');
+  const project = guiRegistry.projectLabel();
+  const html = injectProjectIntoHtml(htmlTemplate, project);
 
   const server = http.createServer(async (req, res) => {
     const url = new URL(req.url, `http://localhost:${port}`);
@@ -302,7 +354,13 @@ async function serveWeb(port) {
 
       if (requestPath === '/api/board') {
         await kanban.migrateEpicGroups();
-        const tasks = await kanban.allTasks();
+        const includeArchived = url.searchParams.get('include_archived') === 'true';
+        const epics = await kanban.listEpicEntities();
+        // GUI: show done-epic tasks; only hide archived unless toggled
+        const tasks = kanban.filterTasksForList(await kanban.allTasks(), epics, {
+          live_only: false,
+          include_archived: includeArchived
+        });
         sendJson(res, 200, tasks);
         return;
       }
@@ -311,7 +369,16 @@ async function serveWeb(port) {
         await kanban.migrateEpicGroups();
         const tasks = await kanban.allTasks();
         const epics = await kanban.listEpicEntities();
-        sendJson(res, 200, epics.map((epic) => kanban.shapeEpic(epic, tasks, { view: 'full' })));
+        const shaped = epics.map((epic) => kanban.shapeEpic(epic, tasks, { view: 'full' }));
+        const includeArchived = url.searchParams.get('include_archived') === 'true';
+        const includeDone = url.searchParams.get('include_done') === 'true';
+        const status = url.searchParams.get('status') || undefined;
+        // GUI default: all non-archived (live + done). Agents use MCP live-only.
+        const liveOnly = url.searchParams.get('live_only') === 'true';
+        const filtered = kanban.filterShapedEpics(shaped, liveOnly
+          ? { include_archived: includeArchived, include_done: includeDone, status }
+          : { live_only: false, include_archived: includeArchived, status });
+        sendJson(res, 200, filtered);
         return;
       }
 
@@ -370,6 +437,33 @@ async function serveWeb(port) {
         return;
       }
 
+      if (req.method === 'DELETE') {
+        const epicDeleteMatch = requestPath.match(/^\/api\/epic-entities\/([^/]+)$/);
+        if (epicDeleteMatch) {
+          const result = await kanban.deleteEpic(epicDeleteMatch[1]);
+          sendJson(res, 200, result);
+          return;
+        }
+
+        const taskDeleteMatch = requestPath.match(/^\/api\/(?:epics|tasks)\/([^/]+)$/);
+        if (taskDeleteMatch) {
+          const result = await kanban.deleteTask(taskDeleteMatch[1]);
+          sendJson(res, 200, result);
+          return;
+        }
+      }
+
+      if (req.method === 'POST') {
+        const epicArchiveMatch = requestPath.match(/^\/api\/epic-entities\/([^/]+)\/(archive|unarchive)$/);
+        if (epicArchiveMatch) {
+          const epic = epicArchiveMatch[2] === 'archive'
+            ? await kanban.archiveEpic(epicArchiveMatch[1])
+            : await kanban.unarchiveEpic(epicArchiveMatch[1]);
+          sendJson(res, 200, kanban.shapeEpic(epic, await kanban.allTasks(), { view: 'full' }));
+          return;
+        }
+      }
+
       if (req.method === 'PATCH') {
         const epicUpdateMatch = requestPath.match(/^\/api\/epic-entities\/([^/]+)$/);
         if (epicUpdateMatch) {
@@ -504,6 +598,7 @@ async function serveWeb(port) {
   });
 
   console.log(`\x1b[1;32m→ Kanban GUI: ${portInfo.url}\x1b[0m`);
+  console.log(`  Project:   ${portInfo.project || project}`);
   console.log(`  Backlog:   ${BACKLOG}`);
   console.log('  Ctrl+C żeby zamknąć');
 }
@@ -617,6 +712,7 @@ async function main() {
     let colFilter = null;
     let epicFilter = null;
     let asJson = false;
+    let includeArchived = false;
 
     for (let i = 1; i < args.length; i++) {
       if (args[i] === '--col' && args[i + 1]) {
@@ -625,14 +721,31 @@ async function main() {
         epicFilter = args[++i];
       } else if (args[i] === '--json') {
         asJson = true;
+      } else if (args[i] === '--include-archived') {
+        includeArchived = true;
       }
     }
 
-    await cliList(colFilter, epicFilter, asJson);
+    await cliList(colFilter, epicFilter, asJson, { include_archived: includeArchived });
   } else if (cmd === 'epic') {
     const sub = args[1];
     if (sub === 'list') {
-      await cliEpicList(args.includes('--json'));
+      let includeArchived = false;
+      let includeDone = false;
+      let status;
+      for (let i = 2; i < args.length; i++) {
+        if (args[i] === '--include-archived') includeArchived = true;
+        else if (args[i] === '--include-done') includeDone = true;
+        else if (args[i] === '--all') {
+          includeArchived = true;
+          includeDone = true;
+        } else if (args[i] === '--status' && args[i + 1]) status = args[++i];
+      }
+      await cliEpicList(args.includes('--json'), {
+        include_archived: includeArchived,
+        include_done: includeDone,
+        status
+      });
     } else if (sub === 'show' && args[2]) {
       await cliEpicShow(args[2]);
     } else if (sub === 'add' && args[2]) {
@@ -645,12 +758,20 @@ async function main() {
       await cliEpicAdd(args[2], { description, goals });
     } else if (sub === 'update' && args[2] && args[3]) {
       await cliEpicUpdate(args[2], parseJsonPayload(args[3]));
+    } else if (sub === 'archive' && args[2]) {
+      await cliEpicArchive(args[2], true);
+    } else if (sub === 'unarchive' && args[2]) {
+      await cliEpicArchive(args[2], false);
+    } else if ((sub === 'rm' || sub === 'delete') && args[2]) {
+      await cliEpicDelete(args[2]);
     } else {
-      console.error('Usage: kanban epic list|show|add|update ...');
+      console.error('Usage: kanban epic list|show|add|update|archive|unarchive|rm ...');
       process.exit(1);
     }
   } else if (cmd === 'show' && args[1]) {
     await cliShow(args[1]);
+  } else if ((cmd === 'rm' || cmd === 'delete') && args[1]) {
+    await cliDelete(args[1]);
   } else if (cmd === 'move' && args[1] && args[2]) {
     await cliMove(args[1], args[2]);
   } else if (cmd === 'add' && args[1]) {

package/gui-registry.js

@@ -21,6 +21,15 @@ function guiPortFilePath() {
   return path.join(BACKLOG, GUI_PORT_FILE);
 }
 
+function projectLabel(cwd = process.cwd()) {
+  const fromEnv = process.env.KANBANGO_PROJECT_NAME;
+  if (fromEnv !== undefined && fromEnv !== null && String(fromEnv).trim()) {
+    return String(fromEnv).trim();
+  }
+  const base = path.basename(String(cwd || '').replace(/[/\\]+$/, ''));
+  return base || 'kanban';
+}
+
 function hashCwdToPort(cwd = process.cwd()) {
   let hash = 0;
   const input = String(cwd);
@@ -79,11 +88,13 @@ async function writeGuiPortFile({ port, pid = process.pid } = {}) {
   }
 
   await ensureBacklogDir();
+  const cwd = process.cwd();
   const data = {
     port: normalizedPort,
     pid,
     url: `http://localhost:${normalizedPort}`,
-    cwd: process.cwd(),
+    cwd,
+    project: projectLabel(cwd),
     started_at: new Date().toISOString()
   };
   await fs.writeFile(guiPortFilePath(), JSON.stringify(data, null, 2), 'utf-8');
@@ -129,11 +140,13 @@ async function discoverRunningGui() {
     pid: info.pid,
     url: info.url || `http://localhost:${info.port}`,
     cwd: info.cwd,
+    project: info.project || projectLabel(info.cwd),
     started_at: info.started_at
   };
 }
 
 module.exports = {
+  projectLabel,
   hashCwdToPort,
   normalizeGuiPort,
   resolvePreferredGuiPort,