kanbango 3.8.0 → 5.1.0

package/AGENTS.md

@@ -8,19 +8,24 @@ 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
-- context: one-shot compass (active or next unblocked planned, else idle); optional `epic`
+- context: omit `operation` = context (wake compass: unblocked active, failed/blocked gate, manual testing/review, else next unblocked planned, else idle); optional `epic`
+- after context: one `show` `view=planning` or `view=execution`; do not re-list
+- `PARSE_ERROR`: corrupt JSON on list/context is an error with file path — never a partial board
 - `depends_on` must be done before active/gates (`TASK_BLOCKED`); cycle → `CIRCULAR_DEPENDENCY`; `files[]` = touched paths
-- 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
+- list_epics default = live only (hides done + archived); `include_archived` / `include_done` / `status` to widen
+- list default hides column=done and tasks under done/archived epics; `include_done`/`include_archived` or `col=done` to widen; show/show_epic by id always works
+- show: `view=planning` for SPEC; `view=execution` while coding; `full` only if needed
+- planning/full task views may return `epic_goals` as the parent compass; empty fields are omitted — 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)
+- move/update/delete/plan_*: `return=none`; subtasks = full array replace (no toggle)
 - cleanup: `delete` (task), `epic_delete` (cascade), `epic_archive` / `epic_unarchive`
 - `steps` on create/plan_create → subtasks (no forced TDD); runner optional; optional plan_*: plan_create → plan_advance → plan_evidence (diff|summary|test_command) → plan_done
+- enter testing|review (and done when gates on) only with `evidence[]` having `diff|summary|test_command`; fail/blocked cannot skip forward — `EVIDENCE_REQUIRED`
+- errors: `next_tool_call` only when repair is unique (`TASK_NOT_FOUND`, `INVALID_TRANSITION`); omit otherwise
 - gui: `status` before `start`; `stop` only owned; `external_running` = do not kill
+- core board has no QA/review dependency; testing/review columns and agent spawns are opt-in
 
 ## Build & Development Commands
 
@@ -39,19 +44,17 @@ npm run mcp
 # or
 node mcp-server.js
 
-# Run tests (lists tasks in JSON format)
+# Full suite (tests/run.js)
 npm test
-# or
-node bin/kanban.js list --json
 
 # Initialize backlog structure
 node bin/kanban.js init
 ```
 
 ### Testing
-The project uses a simple test command that verifies the CLI works:
 ```bash
 npm test
+# single file: node tests/kanban.test.js
 ```
 
 **Single test verification:**
@@ -80,15 +83,17 @@ npm install -g .
 ### File Structure
 ```
 kanbango/
-├── bin/              # CLI executables
-│   ├── kanban.js      # Main CLI with web server
-│   └── kanban-cmd.js  # Alternative CLI (symlink to kanban.js)
-├── kanban.js          # Core business logic module
-├── mcp-server.js      # MCP server implementation
-├── index.js           # Main entry point (module exports)
+├── bin/kanban.js      # CLI + web GUI (bin names: kanban, kanban-cmd)
+├── kanban.js          # Core board logic
+├── mcp-server.js      # MCP server
+├── workflow.js        # Gates + agent spawn
+├── plan.js            # Optional plan_* workflow
+├── agent-playbook.js  # Agent token rules (MCP help)
+├── index.js           # Package exports
 ├── index.html         # Web GUI
-├── backlog/           # Task storage (gitignored)
-└── examples/          # Usage examples
+├── agents/            # qa-tester, temida, qa-e2e-tester
+├── tests/             # *.test.js + run.js
+└── backlog/           # Task storage (gitignored)
 ```
 
 ### Imports

package/API.md

@@ -1,185 +1,73 @@
 # Kanban API for AI Agents
 
-Documentation for interacting with local Kanban system (kanban.py).
-
-## Available Functions
-
-```json
-{
-  "type": "function",
-  "name": "kanban_list",
-  "description": "Get list of all tasks from kanban. Optionally filter by column or epic group.",
-  "parameters": {
-    "type": "object",
-    "properties": {
-      "col": {
-        "type": "string",
-        "enum": ["active", "planned", "icebox", "done"],
-        "description": "Optionally filter by column"
-      },
-      "epic": {
-        "type": "string",
-        "description": "Optionally filter by epic group"
-      },
-      "as_json": {
-        "type": "boolean",
-        "default": true,
-        "description": "Return result as JSON"
-      }
-    },
-    "additionalProperties": false
-  }
-}
-```
+Canonical agent rules: `agent-playbook.js` (`kanban_read` `operation=help`).
+This file is the human map of MCP tools, views, and CLI. Storage is JSON under `backlog/`.
 
-```json
-{
-  "type": "function",
-  "name": "kanban_show",
-  "description": "Get detailed information about a specific task, including subtask list.",
-  "parameters": {
-    "type": "object",
-    "properties": {
-      "task_id": {
-        "type": "string",
-        "description": "Numeric task ID (e.g. '014')"
-      }
-    },
-    "required": ["task_id"],
-    "additionalProperties": false
-  }
-}
-```
+## MCP tools
 
-```json
-{
-  "type": "function",
-  "name": "kanban_add",
-  "description": "Create new task in kanban in specified column and optional epic group.",
-  "parameters": {
-    "type": "object",
-    "properties": {
-      "title": {
-        "type": "string",
-        "description": "Title of new task"
-      },
-      "col": {
-        "type": "string",
-        "enum": ["active", "planned", "icebox", "done"],
-        "default": "planned",
-        "description": "Column to place task in"
-      },
-      "epic": {
-        "type": "string",
-        "default": "—",
-        "description": "Epic group (optional)"
-      }
-    },
-    "required": ["title"],
-    "additionalProperties": false
-  }
-}
-```
+Three tools. `tools/list` descriptions are short; full playbook is `help`.
 
-```json
-{
-  "type": "function",
-  "name": "kanban_move",
-  "description": "Move existing task to different column.",
-  "parameters": {
-    "type": "object",
-    "properties": {
-      "task_id": {
-        "type": "string",
-        "description": "Task ID to move"
-      },
-      "column": {
-        "type": "string",
-        "enum": ["active", "planned", "icebox", "done"],
-        "description": "New column"
-      }
-    },
-    "required": ["task_id", "column"],
-    "additionalProperties": false
-  }
-}
-```
+### `kanban_read`
 
-```json
-{
-  "type": "function",
-  "name": "kanban_update",
-  "description": "Update task fields, including the full subtasks list.",
-  "parameters": {
-    "type": "object",
-    "properties": {
-      "task_id": {
-        "type": "string",
-        "description": "Parent task ID"
-      },
-      "subtasks": {
-        "type": "array",
-        "items": {
-          "type": "object",
-          "properties": {
-            "id": { "type": "string" },
-            "text": { "type": "string" },
-            "done": { "type": "boolean" },
-            "description": { "type": "string" }
-          }
-        }
-      }
-    },
-    "required": ["task_id", "subtasks"],
-    "additionalProperties": false
-  }
-}
-```
+| operation | Role |
+|-----------|------|
+| *(omit)* / `context` | Wake compass: unblocked active, failed/blocked gate, manual testing/review, else next unblocked planned, else idle. Then one `show` (planning/execution). Corrupt JSON → `PARSE_ERROR` |
+| `list` | Tasks. Default `view=summary`. Hides `column=done` and tasks under done/archived epics |
+| `show` | One task (`task_id` required). `view=planning` for SPEC, `execution` while coding, `full` only if needed |
+| `list_epics` | Live epics only (hides done + archived) |
+| `show_epic` | One epic (`epic_id`) |
+| `help` | Playbook from `agent-playbook.js` (no board I/O) |
 
-## Usage Examples
+Widen lists with `include_done`, `include_archived`, `col=done`, or `status`. `show` / `show_epic` by id always work.
 
-```bash
-# List all tasks (JSON)
-python kanban.py list --json
+### `kanban_manage`
 
-# List only active tasks
-python kanban.py list --col active --json
+| action | Role |
+|--------|------|
+| `create` | Task. Hard-required: `title`. Returns `{ok, id, missing?}` not a full echo |
+| `move` | `task_id` + `column` |
+| `update` | Field patch. `subtasks` = full array replace. `adr={decision,why}` appends |
+| `delete` | Task |
+| `epic_create` / `epic_update` / `epic_archive` / `epic_unarchive` / `epic_delete` | Epic containers (`epic_delete` cascades children) |
+| `plan_create` / `plan_advance` / `plan_evidence` / `plan_done` / `plan_status` | Optional accepted-plan workflow |
 
-# Show task details
-python kanban.py show 014
+Writes default `return=none` (including `plan_*`). Use `summary` or `full` only when you need the shaped task or plan echo back.
 
-# Add new task
-python kanban.py add "New function" --col planned --epic "Faza 6"
+### `kanban_gui`
 
-# Move task to different column
-python kanban.py move 014 active
+`status` before `start`. `stop` kills only the GUI this MCP spawned. `external_running` = do not kill.
 
-# Update subtasks
-python kanban.py update 014 '{"subtasks":[{"done":true,"text":"Research"},{"done":false,"text":"Implementation"}]}'
-```
+## Views (sparse)
+
+Empty strings and empty arrays are omitted.
+
+- **summary** — id, title, column, epic, progress, blocked
+- **planning** — SPEC fields (`description`, `specs`, in/out scope, AC, `depends_on`, `epic_goals` parent compass)
+- **execution** — subtasks, workflow, files (no SPEC re-echo)
+- **full** — everything stored
 
-## Kanban Columns
-
-- `active` - in progress (max 1-2 tasks)
-- `planned` - planned for implementation
-- `icebox` - frozen / nice-to-have
-- `done` - completed
-
-## Data Models
-
-### Task
-```json
-{
-  "id": "string",
-  "title": "string",
-  "column": "active|planned|icebox|done",
-  "epic_group": "string",
-  "created": "string",
-  "subtasks": [
-    {
-      "done": "boolean",
-      "text": "string"
-    }
-  ]
-}
+`epic_goals` is the parent epic compass in planning/full views. Empty fields are omitted.
+
+## Columns
+
+`icebox` → `planned` → `active` → `testing` → `review` → `done` (gates optional via `backlog/kanbango.json`).
+`active`→`done` is illegal while testing/review columns are on. Entering a gate (and `done` when gates are on) needs `evidence[]` with `diff` or `summary` or `test_command`.
+
+## Concurrency
+
+Writes from MCP, CLI, and GUI on **one local board** are serialized with `backlog/.board.lock`. A busy lock returns structured `BOARD_LOCKED` (`retryable=true`). This is not distributed storage: two checkouts or a shared network disk are not coordinated.
+
+## CLI
+
+```bash
+kanban list --json
+kanban list --col done --json          # include done column
+kanban show 014
+kanban add "Title" --col planned --epic E001
+kanban move 014 testing
+kanban update 014 '{"subtasks":[{"done":true,"text":"Research"}]}'
+kanban epic list --json
+kanban epic show E001
 ```
+
+Node binary: `bin/kanban.js` (`kanban` and `kanban-cmd` both map here).

package/CHANGELOG.md

@@ -7,7 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Cross-process board lock (`backlog/.board.lock`) so concurrent MCP/CLI/GUI writers on one local board cannot lose creates, moves, evidence, or plan steps. Busy lock returns retryable `BOARD_LOCKED`. `plan_evidence` appends; `plan_advance` marks one subtask done on the locked snapshot.
+- Agent wake (`context`): skip blocked active work; surface failed/blocked gates and manual testing/review; `PARSE_ERROR` on corrupt JSON instead of a partial board. `next_action` requires proof evidence (`diff|summary|test_command`) before suggesting a gate move.
+- Agent cost: `plan_*` honors `return=none` (no subtasks/evidence echo). MCP `show` reuses one board scan. Repeatable probe: `node benchmarks/agent-workflow.js`.
+
+## [5.1.0] - 2026-09-20
+
+### Added
+- OpenCode TUI plugin (`plugins/tui-kanban.tsx`): palette `/kanban` (category Kanban) and shortcut `Ctrl+Alt+K` open the board browser modal and paste a start prompt.
+- `kanban init --opencode` and `mcp-init --opencode` install `tui-kanban.tsx` + `tui-kanban-controller.js` into `.opencode/plugins/` with the same tracked-file / `--force` contract as OpenCode agents.
+- Shared tracked-file copier in `bin/kanban.js` (agents + plugins hash manifests).
+
+## [5.0.0] - 2026-09-20
+
+Kanbango core is now independent of QA, review agents, OpenCode, and external runners.
+
+### Changed
+- Gate columns (`testing` and `review`) are disabled by default.
+- Workflow agents are disabled by default.
+- The default board contains only `icebox`, `planned`, `active`, and `done`.
+- QA/review gates remain available as explicit project configuration.
+
+## [4.0.0] - 2026-09-19
+
+MCP defaults and payload shape changed. Agents that assumed pretty JSON, full-card create echo, `return=summary`, `list` including `done`, `show_epic=full`, or omitted `operation` = `list` must pass those flags explicitly.
+
+### Added
+- MCP errors: `next_tool_call` only when the next call is unique (`TASK_NOT_FOUND`, `INVALID_TRANSITION`); omit for `TASK_BLOCKED`, `CIRCULAR_DEPENDENCY`, `MISSING_REQUIRED_FIELD`, `EVIDENCE_REQUIRED`.
+- Evidence gate: moves into enabled `testing`/`review` (and `done` when those gates exist) require `evidence[]` with `diff`|`summary`|`test_command`; `workflow.status` fail/blocked cannot skip forward. Error `EVIDENCE_REQUIRED` with hint + details.
+- GUI NOW panel: `GET /api/context` (`next_action`); cards/paper show `blocked by` unmet dependency ids. `/api/board` includes computed `blocked`/`unmet_dependencies`.
+
 ### Changed
+- MCP payloads: compact JSON (no pretty-print); omit null/`""`/`[]` from shaped task/epic/context (keep `blocked`/`progress`); summary includes `id`, drops `created`/`epic_group`; `return` defaults to `none`; `show_epic` defaults to `summary`.
+- `view=execution` is runtime only (id/progress/subtasks/workflow/files/blocked); SPEC stays on `view=planning`.
+- `create` / `epic_create` default `{ok, id, missing?}` instead of full-card echo; `return=summary|full` still available.
+- MCP `tools/list`: short tool descriptions; property essays stripped; playbook via `operation=help`. ~2667 → ~1040 tok (chars/4).
+- Default `list` hides `column=done` (including orphans); `include_done` or `col=done` to widen; GUI `live_only=false` unchanged.
+- MCP `kanban_read`: omit `operation` defaults to `context` (was `list`). Explicit `operation=list` unchanged.
+- MCP `tools/list` schemas encode action-specific required fields (`show`→`task_id`, `create`→`title`, `move`→`task_id`+`column`) plus examples.
 - `plan_create` / `detectTestRunner`: missing test runner returns `null` (no `NO_TEST_RUNNER` hard fail)
 - Plan subtasks = only provided `steps` (no forced Write tests / red / green)
 - MCP `create` accepts `steps[]` as subtask shortcut when `subtasks` omitted
@@ -19,7 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Agent-first context snapshot with dependency-aware task selection.
 - `depends_on` DAG validation, cycle detection, blocked/downstream visibility, and `files` scope tracking.
 - Context next actions and `unblocked_tasks` after completing a dependency.
-- Planned follow-up tasks for strict evidence gates, actionable MCP errors, and an agent cockpit GUI.
+- Planned follow-up tasks for strict evidence gates, actionable MCP errors, and an agent cockpit GUI (shipped in 4.0.0).
 
 ## [3.7.0] - 2026-08-26