kanbango 2.1.0 → 2.4.0

package/AGENTS.md

@@ -6,7 +6,7 @@ This document provides build commands, testing procedures, and code style guidel
 
 ### Available Scripts
 ```bash
-# Start web GUI (opens http://localhost:5500)
+# Start web GUI (stable project port in 5510-5999, or KANBANGO_GUI_PORT)
 npm start
 # or
 node bin/kanban.js serve
@@ -14,7 +14,7 @@ node bin/kanban.js serve
 # Start web GUI on custom port
 node bin/kanban.js serve 8080
 
-# Run MCP server
+# Run MCP server (optional auto-GUI: KANBANGO_AUTO_GUI=1)
 npm run mcp
 # or
 node mcp-server.js
@@ -143,7 +143,7 @@ async function parseEpic(filePath, column) {
 
 // Callbacks
 function shortId(epicId) {
-  const match = epicId.match(/^(PI-\d+[\w.]*|BUG-\d+|CHORE-\d+)/);
+  const match = epicId.match(/^(?:[A-Z]+-)?(\d+)/);
   return match ? match[1] : epicId;
 }
 ```
@@ -387,9 +387,9 @@ const args = process.argv.slice(2);  // Skip node and script path
 const cmd = args[0];
 const param1 = args[1];
 
-// Example: node bin/kanban.js move PI-001 done
+// Example: node bin/kanban.js move 001 done
 // args[0] = "move"
-// args[1] = "PI-001"
+// args[1] = "001"
 // args[2] = "done"
 ```
 
@@ -560,7 +560,7 @@ After making changes, verify:
 1. CLI works: `node bin/kanban.js list --json`
 2. Web GUI starts: `node bin/kanban.js serve` (Ctrl+C to stop)
 3. MCP server tools: `echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node mcp-server.js`
-4. All three tools work: kanban_read, kanban_create, kanban_update
+4. All three tools work: kanban_read, kanban_manage, kanban_gui
 
 ## Common Patterns to Avoid
 
@@ -603,4 +603,4 @@ return { content: [{ text: JSON.stringify({ error: error.message }) }], isError:
 - README.md: https://github.com/k0r81/kanbango#readme
 - LLM Agents Guide: LLM_AGENTS.md
 - MCP Server Guide: LLM_AGENTS.md
-- Issues: https://github.com/k0r81/kanbango/issues
+- Issues: https://github.com/k0r81/kanbango/issues

package/API.md

@@ -42,7 +42,7 @@ Documentation for interacting with local Kanban system (kanban.py).
     "properties": {
       "task_id": {
         "type": "string",
-        "description": "Task ID (e.g. 'PI-014-google-calendar')"
+        "description": "Numeric task ID (e.g. '014')"
       }
     },
     "required": ["task_id"],
@@ -108,8 +108,8 @@ Documentation for interacting with local Kanban system (kanban.py).
 ```json
 {
   "type": "function",
-  "name": "kanban_toggle",
-  "description": "Toggle checkbox state for subtask (done/not done).",
+  "name": "kanban_update",
+  "description": "Update task fields, including the full subtasks list.",
   "parameters": {
     "type": "object",
     "properties": {
@@ -117,12 +117,20 @@ Documentation for interacting with local Kanban system (kanban.py).
         "type": "string",
         "description": "Parent task ID"
       },
-      "idx": {
-        "type": "integer",
-        "description": "Subtask index (starting from 0)"
+      "subtasks": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "text": { "type": "string" },
+            "done": { "type": "boolean" },
+            "description": { "type": "string" }
+          }
+        }
       }
     },
-    "required": ["task_id", "idx"],
+    "required": ["task_id", "subtasks"],
     "additionalProperties": false
   }
 }
@@ -138,16 +146,16 @@ python kanban.py list --json
 python kanban.py list --col active --json
 
 # Show task details
-python kanban.py show PI-014-google-calendar
+python kanban.py show 014
 
 # Add new task
 python kanban.py add "New function" --col planned --epic "Faza 6"
 
 # Move task to different column
-python kanban.py move PI-014-google-calendar active
+python kanban.py move 014 active
 
-# Toggle subtask
-python kanban.py toggle PI-014-google-calendar 0
+# Update subtasks
+python kanban.py update 014 '{"subtasks":[{"done":true,"text":"Research"},{"done":false,"text":"Implementation"}]}'
 ```
 
 ## Kanban Columns
@@ -167,7 +175,7 @@ python kanban.py toggle PI-014-google-calendar 0
   "column": "active|planned|icebox|done",
   "epic_group": "string",
   "created": "string",
-  "tasks": [
+  "subtasks": [
     {
       "done": "boolean",
       "text": "string"

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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).
 
+## [2.4.0] - 2026-07-27
+
+### Added
+- Opt-in GUI auto-start with MCP via `KANBANGO_AUTO_GUI=1`
+- Stable per-project GUI port (hash of cwd in `5510–5999`), overridable with `KANBANGO_GUI_PORT` or `kanban serve [PORT]`
+- `backlog/.kanbango-gui.json` port file so the real URL is always discoverable
+- `kanban_gui status` discovers a running GUI even outside the MCP child-process tracker
+
+### Changed
+- `kanban serve` default port is no longer hard-coded `5500`; uses preferred/stable port resolution
+- `kanban_gui start` waits for the server to publish its actual listen port before returning
+
+## [2.3.0] - 2026-07-27
+
+### Added
+- `in_scope` and `out_of_scope` fields (arrays of strings) for task boundaries in planning/execution/full views
+- MCP `kanban_manage` create/update support for `in_scope` and `out_of_scope`
+- Web GUI edit/view sections for In Scope and Out of Scope (muted styling for exclusions)
+- Markdown migrate support for `## In Scope` / `## Out of Scope` (and PL headings)
+
+### Fixed
+- HTTP API now forwards `test_cases` on create and update (GUI saves were previously dropped)
+
+## [2.2.0] - 2026-07-09
+
+### Changed
+- MCP tools consolidated from 6 to 3:
+  - `kanban_create` + `kanban_update` merged into `kanban_manage` with `action` parameter (`create` | `move` | `update`)
+  - `kanban_gui_start` + `kanban_gui_stop` + `kanban_gui_status` merged into `kanban_gui` with `action` parameter (`start` | `stop` | `status`)
+  - `kanban_read` unchanged
+- `kanban_manage` subtask edits now use full list updates via `update`; `toggle` action removed
+
 ## [2.1.0] - 2026-07-09
 
 ### Added

package/LLM_AGENTS.md

@@ -68,7 +68,7 @@ Read tasks from kanban board. Can list all tasks, filter by column/epic, or get
 ```json
 {
   "operation": "list",  // "list" or "show"
-  "task_id": "PI-014-google-calendar",  // Required for "show"
+  "task_id": "014",  // Required for "show"
   "col": "planned",  // Optional: "active" | "planned" | "icebox" | "done"
   "epic": "Phase 1"  // Optional: filter by epic group
 }
@@ -95,7 +95,7 @@ Get specific task details:
 ```json
 {
   "operation": "show",
-  "task_id": "PI-014-google-calendar"
+  "task_id": "014"
 }
 ```
 
@@ -103,12 +103,12 @@ Get specific task details:
 ```json
 [
   {
-    "id": "PI-014-google-calendar",
-    "title": "PI-014: Google Calendar Integration",
+    "id": "014",
+    "title": "Google Calendar Integration",
     "column": "active",
     "epic_group": "Phase 1",
     "created": "2026-03-15",
-    "tasks": [
+    "subtasks": [
       { "done": true, "text": "API authentication" },
       { "done": false, "text": "Event synchronization" }
     ]
@@ -119,232 +119,195 @@ Get specific task details:
 **Response (show):**
 ```json
 {
-  "id": "PI-014-google-calendar",
-  "title": "PI-014: Google Calendar Integration",
+  "id": "014",
+  "title": "Google Calendar Integration",
   "column": "active",
   "epic_group": "Phase 1",
   "created": "2026-03-15",
-  "tasks": [
-    { "done": true, "text": "API authentication" },
-    { "done": false, "text": "Event synchronization" }
-  ]
+    "subtasks": [
+      { "done": true, "text": "API authentication" },
+      { "done": false, "text": "Event synchronization" }
+    ]
 }
 ```
 
 ---
 
-### 2. kanban_create
-
-Create a new task on kanban board.
+### 2. kanban_manage
 
-**Parameters:**
-```json
-{
-  "title": "New feature implementation",  // Required
-  "col": "planned",  // Optional: "active" | "planned" | "icebox" | "done" (default: "planned")
-  "epic": "Phase 1"  // Optional: epic group name (default: "—")
-}
-```
+Create, move, or patch-update kanban tasks. Single tool for all mutations.
 
-**Examples:**
+**Actions:**
+- `create` - Create a new task with optional rich planning fields
+- `move` - Move a task to a different column
+- `update` - Apply a field-level patch to any task attributes
 
-Create task with defaults:
+**Parameters (create):**
 ```json
 {
-  "title": "Add user authentication"
+  "action": "create",
+  "title": "New feature",  // Required
+  "col": "planned",  // Optional, default "planned"
+  "epic": "Phase 1",  // Optional, default "—"
+  "description": "Context and plan",
+  "specs": "Technical constraints",
+  "in_scope": ["What is included"],
+  "out_of_scope": ["What is excluded"],
+  "acceptance_criteria": ["Must work"],
+  "test_cases": ["Verify X"],
+  "subtasks": [{"text": "Do it", "done": false}],
+  "notes": "Freeform notes"
 }
 ```
 
-Create task with custom column and epic:
+**Parameters (move):**
 ```json
 {
-  "title": "Database optimization",
-  "col": "planned",
-  "epic": "Performance"
+  "action": "move",
+  "task_id": "014",  // Required
+  "column": "done"  // Required: target column
 }
 ```
 
-**Response:**
+**Parameters (update):**
 ```json
 {
-  "id": "PI-015-database-optimization",
-  "title": "PI-015: Database optimization",
-  "column": "planned",
-  "epic_group": "Performance",
-  "created": "2026-03-16",
-  "tasks": []
+  "action": "update",
+  "task_id": "014",  // Required
+  "patch": {"description": "New context"},  // Field-level patch object
+  "title": "New title",  // Shortcut, equivalent to patch.title
+  "subtasks": [{"text": "A", "done": true}],  // Preferred full subtask list
+  "return": "summary"  // "none" | "summary" | "full" (default "summary")
 }
 ```
 
----
-
-### 3. kanban_update
-
-Update existing tasks on kanban board. Can move tasks between columns, toggle subtask completion, or update task details.
-
-**Operations:**
-- `move` - Move task to different column
-- `toggle` - Toggle subtask completion
-- `update` - Update task title and/or subtask list
+**Examples:**
 
-**Parameters:**
+Create a task:
 ```json
 {
-  "operation": "move",  // "move" | "toggle" | "update"
-  "task_id": "PI-014-google-calendar",  // Required
-  "column": "done",  // Required for "move"
-  "idx": 0,  // Required for "toggle"
-  "title": "Updated title",  // Optional for "update"
-  "tasks": [  // Optional for "update"
-    { "done": true, "text": "Task 1" },
-    { "done": false, "text": "Task 2" }
-  ]
+  "action": "create",
+  "title": "Database optimization",
+  "col": "planned",
+  "epic": "Performance"
 }
 ```
 
-**Examples:**
-
 Move task to done:
 ```json
 {
-  "operation": "move",
-  "task_id": "PI-014-google-calendar",
+  "action": "move",
+  "task_id": "014",
   "column": "done"
 }
 ```
 
-Toggle first subtask:
+Patch-update task fields:
 ```json
 {
-  "operation": "toggle",
-  "task_id": "PI-014-google-calendar",
-  "idx": 0
+  "action": "update",
+  "task_id": "014",
+  "patch": {
+    "title": "Updated title",
+    "description": "New implementation plan",
+    "epic_group": "Phase 2",
+    "subtasks": [
+      { "id": "st-1", "text": "Research", "done": true },
+      { "id": "st-2", "text": "Implementation", "done": false }
+    ]
+  }
 }
 ```
 
-Update task title:
-```json
-{
-  "operation": "update",
-  "task_id": "PI-014-google-calendar",
-  "title": "Google Calendar API Integration"
-}
-```
+---
 
-Update subtasks:
-```json
-{
-  "operation": "update",
-  "task_id": "PI-014-google-calendar",
-  "tasks": [
-    { "done": true, "text": "API authentication" },
-    { "done": true, "text": "Event synchronization" },
-    { "done": false, "text": "Error handling" }
-  ]
-}
-```
+### 3. kanban_gui
 
-**Response (move):**
-```json
-{
-  "success": true,
-  "message": "Moved PI-014-google-calendar to done"
-}
-```
+Control the web GUI server: start, stop, or check status.
 
-**Response (toggle/update):**
-```json
-{
-  "id": "PI-014-google-calendar",
-  "title": "PI-014: Google Calendar Integration",
-  "column": "active",
-  "epic_group": "Phase 1",
-  "created": "2026-03-15",
-  "tasks": [
-    { "done": false, "text": "API authentication" },
-    { "done": false, "text": "Event synchronization" }
-  ]
-}
-```
+**Port resolution (start):**
+1. Explicit `port` argument, if provided
+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`).
 
-### 4. kanban_gui_start
+**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.
 
-Start the web GUI server for the kanban board.
+**Actions:**
+- `start` - Launch the GUI server
+- `stop` - Kill the GUI server
+- `status` - Check if the GUI is running (reads live process or port file)
 
 **Parameters:**
 ```json
 {
-  "port": 5500  // Optional: port for GUI (default 5500)
+  "action": "start",  // "start" | "stop" | "status"
+  "port": 5821  // Optional, only for "start"
 }
 ```
 
 **Examples:**
 
-Start GUI on default port:
+Start GUI (stable project port):
 ```json
-{}
+{
+  "action": "start"
+}
 ```
 
 Start GUI on custom port:
 ```json
 {
+  "action": "start",
   "port": 8080
 }
 ```
 
-**Response:**
+Stop the GUI:
 ```json
 {
-  "status": "started",
-  "port": 5500,
-  "pid": 12345,
-  "url": "http://localhost:5500"
+  "action": "stop"
 }
 ```
 
----
-
-### 5. kanban_gui_stop
-
-Stop the web GUI server if it is running.
-
-**Parameters:**
+Check status:
 ```json
-{}
+{
+  "action": "status"
+}
 ```
 
-**Response:**
+**Response (start):**
 ```json
 {
-  "status": "stopping",
-  "port": 5500
+  "status": "started",
+  "port": 5623,
+  "pid": 12345,
+  "url": "http://localhost:5623"
 }
 ```
 
----
-
-### 6. kanban_gui_status
-
-Get status of the web GUI server.
-
-**Parameters:**
+**Response (stop):**
 ```json
-{}
+{
+  "status": "stopping",
+  "port": 5623,
+  "pid": 12345
+}
 ```
 
-**Response (running):**
+**Response (status - running):**
 ```json
 {
   "status": "running",
-  "port": 5500,
+  "port": 5623,
   "pid": 12345,
-  "url": "http://localhost:5500"
+  "url": "http://localhost:5623"
 }
 ```
 
-**Response (not running):**
+**Response (status - not running):**
 ```json
 {
   "status": "not_running"
@@ -359,15 +322,24 @@ Get status of the web GUI server.
 
 ```json
 {
-  "id": "string",  // Unique task identifier (e.g., "PI-014-google-calendar")
-  "title": "string",  // Full title with ID prefix
+  "id": "string",  // Numeric task identifier (e.g., "014")
+  "title": "string",  // Task title, kept separate from the ID
   "column": "string",  // "active" | "planned" | "icebox" | "done"
   "epic_group": "string",  // Epic group name or "—"
   "created": "string",  // Creation date (YYYY-MM-DD)
-  "tasks": [
+  "description": "string",  // High-level context
+  "specs": "string",  // Technical constraints
+  "in_scope": ["string"],  // What this task includes
+  "out_of_scope": ["string"],  // Explicit non-goals
+  "acceptance_criteria": ["string"],
+  "test_cases": ["string"],
+  "notes": "string",
+  "subtasks": [
     {
-      "done": "boolean",  // Subtask completion status
-      "text": "string"  // Subtask description
+      "id": "string",
+      "done": "boolean",
+      "text": "string",
+      "description": "string"
     }
   ]
 }
@@ -387,51 +359,43 @@ Get status of the web GUI server.
 ### Pattern 1: Task Discovery
 
 ```json
-// List all active tasks
-{ "operation": "list", "col": "active" }
+{ "tool": "kanban_read", "arguments": { "operation": "list", "col": "active" } }
 ```
 
 ### Pattern 2: Task Creation Workflow
 
 ```json
 // 1. Create task
-{ "title": "New feature", "col": "planned", "epic": "Phase 1" }
+{ "tool": "kanban_manage", "arguments": { "action": "create", "title": "New feature", "col": "planned", "epic": "Phase 1" } }
 
 // 2. Get task details to see generated ID
-{ "operation": "show", "task_id": "PI-015-new-feature" }
+{ "tool": "kanban_read", "arguments": { "operation": "show", "task_id": "015" } }
 
 // 3. Update with subtasks
-{
-  "operation": "update",
-  "task_id": "PI-015-new-feature",
-  "tasks": [
-    { "done": false, "text": "Research" },
-    { "done": false, "text": "Implementation" }
-  ]
-}
+{ "tool": "kanban_manage", "arguments": { "action": "update", "task_id": "015", "subtasks": [{"done": false, "text": "Research"}, {"done": false, "text": "Implementation"}] } }
 ```
 
 ### Pattern 3: Task Progression
 
 ```json
 // Move from planned → active
-{ "operation": "move", "task_id": "PI-015", "column": "active" }
+{ "tool": "kanban_manage", "arguments": { "action": "move", "task_id": "015", "column": "active" } }
 
-// Mark subtask complete
-{ "operation": "toggle", "task_id": "PI-015", "idx": 0 }
+// Update subtasks in one call
+{ "tool": "kanban_manage", "arguments": { "action": "update", "task_id": "015", "subtasks": [{ "done": true, "text": "Research" }, { "done": false, "text": "Implementation" }] } }
 
 // Move from active → done
-{ "operation": "move", "task_id": "PI-015", "column": "done" }
+{ "tool": "kanban_manage", "arguments": { "action": "move", "task_id": "015", "column": "done" } }
 ```
 
 ### Pattern 4: Epic Management
 
 ```json
 // List all tasks in an epic
-{ "operation": "list", "epic": "Performance" }
+{ "tool": "kanban_read", "arguments": { "operation": "list", "epic": "Performance" } }
 
 // Create task in specific epic
-{ "title": "Cache optimization", "epic": "Performance" }
+{ "tool": "kanban_manage", "arguments": { "action": "create", "title": "Cache optimization", "epic": "Performance" } }
 ```
 
 ---
@@ -439,30 +403,32 @@ Get status of the web GUI server.
 ## Best Practices for LLM Agents
 
 1. **Always use `kanban_read` first** - Discover existing tasks before creating new ones
-2. **Use `col` filter** - Narrow down to relevant column when listing
-3. **Use `epic` grouping** - Organize tasks by features/phases
-4. **Work through subtasks** - Toggle each subtask as you complete them
-5. **Move tasks through workflow** - planned → active → done progression
-6. **Use `show` operation** - Get full task details including subtasks
-7. **Handle task IDs** - Always use the full task ID returned from create/show
+2. **Numeric task lookup** - Task IDs are zero-padded numbers (e.g. `"035"`). Unpadded numbers such as `"35"` also work in any `task_id` parameter.
+3. **Use `col` filter** - Narrow down to relevant column when listing
+4. **Use `epic` grouping** - Organize tasks by features/phases
+5. **Work through subtasks** - Toggle each subtask as you complete them
+6. **Move tasks through workflow** - planned → active → done progression
+7. **Use `show` operation** - Get full task details including subtasks
+8. **Handle task IDs** - Always use the full task ID returned from create/show
 
 ---
 
 ## Error Handling
 
-All tools return error messages in this format:
+All tools return structured error responses:
 
 ```json
 {
-  "error": "Error message description"
+  "error": {
+    "code": "TASK_NOT_FOUND",
+    "message": "Task 999 was not found",
+    "hint": "Call kanban_read with operation=list to discover valid task ids",
+    "details": {},
+    "retryable": false
+  }
 }
 ```
 
-Common errors:
-- `"Task not found: PI-999"` - Task ID doesn't exist
-- `"Failed to move task: PI-999"` - Move operation failed
-- `"task_id is required for 'show' operation"` - Missing required parameter
-
 ---
 
 ## Installation for Users