scriptoriumadmin/veritas-kanban
1
0
Fork 0
mirror of https://github.com/BradGroux/veritas-kanban.git synced 2026-08-28 02:44:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: update all documentation for v1.2.0 + v1.3.0

Browse source 
- Bump all package versions to 1.3.0
- README: version badge, blocked column, new feature highlights
- CHANGELOG: full v1.2.0 and v1.3.0 entries
- FEATURES.md: GitHub sync, activity feed, standup summary sections
- FEATURES.md: storage architecture, API envelope docs, new CLI commands
- FEATURES.md: updated API endpoints table and response format docs
This commit is contained in:
Brad Groux 2026-01-31 23:33:37 -06:00
parent 879b095096
commit 9369ca8bcf
8 changed files with 301 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

96
CHANGELOG.md
View file

@ -9,6 +9,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
---
## [1.3.0] - 2026-02-01
### ✨ Highlights
- **GitHub Issues Bidirectional Sync** — Import issues with the `kanban` label and push status changes back to GitHub
- **Activity Feed** — Full-page chronological activity feed with filtering, real-time updates, and compact/detailed toggle
- **Daily Standup Summary** — Generate standup reports via API or CLI with completed, in-progress, blocked, and upcoming sections
### Added
#### GitHub Issues Sync (#21)
- `GitHubSyncService` (464 lines) with polling, label-based field mapping, and circuit breaker
- Inbound: import issues with `kanban` label as tasks
- Outbound: push status changes (done → close issue, reopen on todo/in-progress/blocked) and comments
- Label mapping: `priority:high` → priority field, `type:story` → type field
- Config: `.veritas-kanban/integrations.json`, state: `.veritas-kanban/github-sync.json`
- `TaskGitHub` interface in shared types: `{issueNumber, repo, syncedAt?}`
- New API endpoints:
- `POST /api/github/sync` — trigger manual sync
- `GET /api/github/sync/status` — last sync info
- `GET /api/github/sync/config` — get config
- `PUT /api/github/sync/config` — update config
- `GET /api/github/sync/mappings` — list issue↔task mappings
- New CLI commands: `vk github sync`, `vk github status`, `vk github config`, `vk github mappings`
#### Activity Feed (#33)
- Full-page chronological activity feed accessible from header nav (ListOrdered icon)
- `agent` field added to Activity interface
- `ActivityFilters` for combinable filtering (agent, type, taskId, since, until)
- `GET /api/activity` enhanced with query params: `?agent=X&type=Y&taskId=Z&since=ISO&until=ISO`
- `GET /api/activity/filters` — distinct agents and types for filter dropdowns
- `ActivityFeed.tsx` component with day grouping, 15 activity type icons, filter bar, compact/detailed toggle
- Infinite scroll via IntersectionObserver
- Real-time WebSocket updates
- `ViewContext` for board ↔ activity navigation
#### Daily Standup Summary (#34)
- `GET /api/summary/standup?date=YYYY-MM-DD&format=json|markdown|text`
- Sections: completed, in-progress, blocked, upcoming, stats
- `generateStandupMarkdown()` and `generateStandupText()` in SummaryService
- CLI: `vk summary standup` with `--yesterday`, `--date YYYY-MM-DD`, `--json`, `--text` flags
- 12 new tests
### Changed
- MAX_ACTIVITIES increased from 1,000 to 5,000
---
## [1.2.0] - 2026-02-01
### ✨ Highlights
- **Standardized API Response Envelope** — All endpoints return a consistent `{success, data, meta}` format with typed error classes
- **Abstract File Storage** — Repository pattern decouples services from the filesystem
- **Blocked Task Status** — Full support for blocked tasks across MCP, CLI, and board
### Added
#### Standardize API Response Envelope (#2)
- 4 new error classes: `UnauthorizedError`, `ForbiddenError`, `BadRequestError`, `InternalError` (in `middleware/error-handler.ts`)
- `sendPaginated(res, items, {page, limit, total})` helper for pagination metadata in envelope
- Response envelope format:
- Success: `{success: true, data, meta: {timestamp, requestId}}`
- Error: `{success: false, error: {code, message, details?}, meta}`
- Pagination: `meta` includes `{page, limit, total, totalPages}` on paginated endpoints
#### Abstract File Storage (#6)
- 5 new repository interfaces: `ActivityRepository`, `TemplateRepository`, `StatusHistoryRepository`, `ManagedListRepository`, `TelemetryRepository`
- `StorageProvider` extended with new repositories
- `fs-helpers.ts` — centralized filesystem access (only file that imports `fs`)
#### Blocked Task Status (#32)
- MCP tools Zod/JSON schema definitions updated for blocked status
- MCP active tasks filter updated to include blocked
- CLI help text updated
- CLI status color: blocked = red
### Changed
- All 11 route files standardized — zero ad-hoc `{error: "..."}` patterns
- Auth middleware errors standardized to use typed error classes
- All 10 services migrated off direct `fs` imports to use `fs-helpers.ts`
---
## [1.1.0] - 2026-01-31
### ✨ Highlights
@ -242,6 +334,8 @@ Veritas Kanban is an AI-native project management board built for developers and
_Built by [Digital Meld](https://digitalmeld.io) — AI-driven enterprise automation._
[unreleased]: https://github.com/BradGroux/veritas-kanban/compare/v1.1.0...HEAD
[unreleased]: https://github.com/BradGroux/veritas-kanban/compare/v1.3.0...HEAD
[1.3.0]: https://github.com/BradGroux/veritas-kanban/compare/v1.2.0...v1.3.0
[1.2.0]: https://github.com/BradGroux/veritas-kanban/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/BradGroux/veritas-kanban/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/BradGroux/veritas-kanban/releases/tag/v1.0.0

31
README.md
View file

@ -10,7 +10,7 @@ Built for developers who want a visual Kanban board that works with autonomous c
[![CI](https://github.com/BradGroux/veritas-kanban/actions/workflows/ci.yml/badge.svg)](https://github.com/BradGroux/veritas-kanban/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](CHANGELOG.md)
[![Version](https://img.shields.io/badge/version-1.3.0-blue.svg)](CHANGELOG.md)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
@ -92,7 +92,7 @@ Open [http://localhost:3000](http://localhost:3000) — that's it. The board aut
![Drag-and-drop Kanban demo](assets/demo-drag_drop.gif)
- **Drag-and-drop Kanban** — Move tasks across To Do, In Progress, Review, Done
- **Drag-and-drop Kanban** — Move tasks across To Do, In Progress, Blocked, Done
- **Markdown storage** — Human-readable task files with YAML frontmatter
- **Dark/light mode** — Toggle between dark and light themes in Settings
@ -113,6 +113,12 @@ Open [http://localhost:3000](http://localhost:3000) — that's it. The board aut
- **Multiple attempts** — Retry with different agents, preserve history
- **Running indicator** — Visual feedback when agents are working
### 🔄 Visibility & Automation
- **GitHub Issues sync** — Bidirectional sync between GitHub Issues and your board (inbound import, outbound status/comment push)
- **Activity feed** — Full-page chronological activity feed with filtering by agent, type, and date; real-time WebSocket updates; compact/detailed toggle
- **Daily standup summary** — Generate standup reports via API or CLI (`vk summary standup`) with completed, in-progress, blocked, and upcoming sections
### 🗂️ Organization
![Task detail features demo](assets/demo-task.gif)
@ -289,7 +295,14 @@ vk agents:complete <id> -s # Mark agent complete
# Utilities
vk summary # Project stats
vk summary standup # Daily standup summary
vk notify:pending # Check notifications
# GitHub sync
vk github sync # Trigger manual sync
vk github status # Show sync status
vk github config # View/update configuration
vk github mappings # List issue↔task mappings
```
---
@ -329,6 +342,20 @@ curl -X POST http://localhost:3001/api/agents/<id>/complete \
-d '{"success": true, "summary": "What was done"}'
```
### GitHub Issues Sync
```bash
# Trigger a manual sync
curl -X POST http://localhost:3001/api/github/sync \
-H "X-API-Key: $YOUR_KEY"
# Check sync status
curl http://localhost:3001/api/github/sync/status \
-H "X-API-Key: $YOUR_KEY"
```
Issues with the `kanban` label are imported as tasks. Status changes push back (done → close, reopen on todo/in-progress/blocked). Labels like `priority:high` and `type:story` map to task fields. Configure in `.veritas-kanban/integrations.json`.
### OpenClaw (Native)
```bash

2
cli/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@veritas-kanban/cli",
"version": "1.0.0",
"version": "1.3.0",
"description": "CLI for Veritas Kanban task management",
"type": "module",
"bin": {

209
docs/FEATURES.md
View file

@ -11,6 +11,9 @@ Complete feature reference for Veritas Kanban. For a quick overview, see the [RE
- [Sprint Management](#sprint-management)
- [Code Workflow](#code-workflow)
- [AI Agent Integration](#ai-agent-integration)
- [GitHub Issues Sync](#github-issues-sync)
- [Activity Feed](#activity-feed)
- [Daily Standup](#daily-standup)
- [CLI](#cli)
- [MCP Server](#mcp-server)
- [Security](#security)
@ -19,6 +22,7 @@ Complete feature reference for Veritas Kanban. For a quick overview, see the [RE
- [Settings & Customization](#settings--customization)
- [API](#api)
- [Notifications](#notifications)
- [Storage & Architecture](#storage--architecture)
- [Infrastructure & DevOps](#infrastructure--devops)
- [Testing](#testing)
- [Accessibility](#accessibility)
@ -162,6 +166,63 @@ First-class support for autonomous coding agents.
---
## GitHub Issues Sync
Bidirectional sync between GitHub Issues and your Kanban board.
- **Inbound sync** — Issues with the `kanban` label are automatically imported as tasks
- **Outbound sync** — Status changes push back to GitHub: done → close issue, reopen on todo/in-progress/blocked
- **Comment sync** — Comments are synced between GitHub Issues and task comments
- **Label mapping** — GitHub labels map to task fields: `priority:high` → priority, `type:story` → type
- **Circuit breaker** — Automatic failure detection and backoff for GitHub API calls
- **Polling** — Configurable polling interval for checking new/updated issues
- **Configuration** — Stored in `.veritas-kanban/integrations.json`; sync state in `.veritas-kanban/github-sync.json`
- **`TaskGitHub` interface** — Shared type with `{issueNumber, repo, syncedAt?}` fields on synced tasks
- **API endpoints:**
- `POST /api/github/sync` — Trigger manual sync
- `GET /api/github/sync/status` — Last sync info (timestamp, counts, errors)
- `GET /api/github/sync/config` — Get sync configuration
- `PUT /api/github/sync/config` — Update sync configuration
- `GET /api/github/sync/mappings` — List issue↔task mappings
- **CLI commands:** `vk github sync`, `vk github status`, `vk github config`, `vk github mappings`
---
## Activity Feed
Full-page chronological activity feed for project-wide visibility.
- **Dedicated page** — Accessible from header nav (ListOrdered icon) via `ViewContext` for board ↔ activity navigation
- **Day grouping** — Activities grouped by day with clear date headers
- **15 activity type icons** — Visual icons for each activity type (created, updated, status changed, agent started, etc.)
- **Filter bar** — Combinable filters: agent, type, taskId, date range (since/until)
- **Filter dropdowns** — Populated from `GET /api/activity/filters` (distinct agents and types)
- **Compact/detailed toggle** — Switch between compact summary view and detailed expanded view
- **Infinite scroll** — Loads more activities on scroll via IntersectionObserver
- **Real-time updates** — New activities appear live via WebSocket
- **Agent field** — Activities include the `agent` field for filtering by which agent performed the action
- **Capacity** — MAX_ACTIVITIES increased from 1,000 to 5,000
---
## Daily Standup
Generate daily standup summary reports via API or CLI.
- **Standup endpoint** — `GET /api/summary/standup?date=YYYY-MM-DD&format=json|markdown|text`
- **Report sections:** Completed (tasks done that day), In-Progress (active work), Blocked (with reasons), Upcoming (next priorities), Stats (counts and velocity)
- **Multiple formats:**
- `json` — Structured data for programmatic consumption
- `markdown` — Formatted markdown via `generateStandupMarkdown()`
- `text` — Plain text via `generateStandupText()`
- **CLI:** `vk summary standup` with flags:
- `--yesterday` — Generate for previous day
- `--date YYYY-MM-DD` — Generate for a specific date
- `--json` — JSON output
- `--text` — Plain text output
---
## CLI
The `vk` command-line tool for terminal-first workflows.
@ -194,14 +255,24 @@ The `vk` command-line tool for terminal-first workflows.
| `vk automation:start <id>` | `as` | Start an automation task |
| `vk automation:complete <id>` | `ac` | Mark automation complete or failed |
### GitHub Sync Commands
| Command | Description |
| -------------------- | ------------------------------------------------- |
| `vk github sync` | Trigger a manual GitHub Issues sync |
| `vk github status` | Show last sync status (timestamp, counts, errors) |
| `vk github config` | View or update GitHub sync configuration |
| `vk github mappings` | List issue↔task mappings |
### Utility Commands
| Command | Description |
| --------------------- | ------------------------------------------------------------------- |
| `vk summary` | Project stats: status counts, project progress, high-priority items |
| `vk notify <message>` | Create a notification (`--type`, `--title`, `--task` options) |
| `vk notify:check` | Check for tasks that need notifications |
| `vk notify:pending` | Get pending notifications formatted for Teams |
| Command | Description |
| --------------------- | ------------------------------------------------------------------------------ |
| `vk summary` | Project stats: status counts, project progress, high-priority items |
| `vk summary standup` | Daily standup summary (`--yesterday`, `--date YYYY-MM-DD`, `--json`, `--text`) |
| `vk notify <message>` | Create a notification (`--type`, `--title`, `--task` options) |
| `vk notify:check` | Check for tasks that need notifications |
| `vk notify:pending` | Get pending notifications formatted for Teams |
All commands support `--json` output for machine consumption.
@ -405,35 +476,38 @@ RESTful API designed for both human and AI agent consumption.
### Endpoints
| Route Prefix | Description |
| ------------------------------- | ----------------------------------------------- |
| `/api/v1/tasks` | Task CRUD, listing, reordering |
| `/api/v1/tasks/archived` | Archive listing, restore |
| `/api/v1/tasks/:id/time` | Time tracking (start, stop, entries) |
| `/api/v1/tasks/:id/comments` | Comments (add, edit, delete) |
| `/api/v1/tasks/:id/subtasks` | Subtask management |
| `/api/v1/tasks/:id/attachments` | File attachments (upload, download, delete) |
| `/api/v1/config` | Board configuration |
| `/api/v1/settings` | Feature settings |
| `/api/v1/agents` | Agent start, stop, status, attempts, completion |
| `/api/v1/agent/status` | Global agent status indicator |
| `/api/v1/automation` | Automation task lifecycle |
| `/api/v1/diff` | Diff summaries and file diffs |
| `/api/v1/conflicts` | Merge conflict status and resolution |
| `/api/v1/github` | GitHub PR creation |
| `/api/v1/summary` | Project summary and memory-formatted summary |
| `/api/v1/notifications` | Notification CRUD and Teams-formatted pending |
| `/api/v1/templates` | Task template management |
| `/api/v1/task-types` | Custom task type management |
| `/api/v1/projects` | Project list management |
| `/api/v1/sprints` | Sprint list management |
| `/api/v1/activity` | Activity log |
| `/api/v1/status-history` | Task status history and daily summary |
| `/api/v1/preview` | Markdown preview rendering |
| `/api/v1/telemetry` | Telemetry event recording and querying |
| `/api/v1/metrics` | Dashboard metrics and task-level metrics |
| `/api/v1/traces` | Request traces |
| `/api/v1/digest` | Daily digest generation |
| Route Prefix | Description |
| ------------------------------- | ------------------------------------------------------------- |
| `/api/v1/tasks` | Task CRUD, listing, reordering |
| `/api/v1/tasks/archived` | Archive listing, restore |
| `/api/v1/tasks/:id/time` | Time tracking (start, stop, entries) |
| `/api/v1/tasks/:id/comments` | Comments (add, edit, delete) |
| `/api/v1/tasks/:id/subtasks` | Subtask management |
| `/api/v1/tasks/:id/attachments` | File attachments (upload, download, delete) |
| `/api/v1/config` | Board configuration |
| `/api/v1/settings` | Feature settings |
| `/api/v1/agents` | Agent start, stop, status, attempts, completion |
| `/api/v1/agent/status` | Global agent status indicator |
| `/api/v1/automation` | Automation task lifecycle |
| `/api/v1/diff` | Diff summaries and file diffs |
| `/api/v1/conflicts` | Merge conflict status and resolution |
| `/api/v1/github` | GitHub PR creation and Issues sync |
| `/api/v1/github/sync` | GitHub Issues sync (trigger, status, config, mappings) |
| `/api/v1/summary` | Project summary, memory-formatted summary, and standup |
| `/api/v1/summary/standup` | Daily standup summary (json, markdown, text) |
| `/api/v1/notifications` | Notification CRUD and Teams-formatted pending |
| `/api/v1/templates` | Task template management |
| `/api/v1/task-types` | Custom task type management |
| `/api/v1/projects` | Project list management |
| `/api/v1/sprints` | Sprint list management |
| `/api/v1/activity` | Activity log with filtering (agent, type, taskId, date range) |
| `/api/v1/activity/filters` | Distinct agents and types for activity filter dropdowns |
| `/api/v1/status-history` | Task status history and daily summary |
| `/api/v1/preview` | Markdown preview rendering |
| `/api/v1/telemetry` | Telemetry event recording and querying |
| `/api/v1/metrics` | Dashboard metrics and task-level metrics |
| `/api/v1/traces` | Request traces |
| `/api/v1/digest` | Daily digest generation |
### Authentication Methods
@ -453,7 +527,56 @@ RESTful API designed for both human and AI agent consumption.
### Response Format
- JSON responses with consistent error format
All responses use a standardized envelope format:
**Success:**
```json
{
"success": true,
"data": { ... },
"meta": {
"timestamp": "2026-02-01T00:00:00.000Z",
"requestId": "uuid-v4"
}
}
```
**Error:**
```json
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Task not found",
"details": { ... }
},
"meta": {
"timestamp": "2026-02-01T00:00:00.000Z",
"requestId": "uuid-v4"
}
}
```
**Pagination** (on paginated endpoints via `sendPaginated` helper):
```json
{
"success": true,
"data": [ ... ],
"meta": {
"timestamp": "...",
"requestId": "...",
"page": 1,
"limit": 25,
"total": 142,
"totalPages": 6
}
}
```
- 4 typed error classes: `UnauthorizedError`, `ForbiddenError`, `BadRequestError`, `InternalError`
- `X-API-Version` header on all responses
- `X-Request-Id` header for request tracing
- `Last-Modified` headers for cache validation
@ -474,6 +597,18 @@ Event-driven notifications with Teams integration.
---
## Storage & Architecture
Abstract storage layer that decouples business logic from the filesystem.
- **Repository pattern** — 5 repository interfaces abstract data access: `ActivityRepository`, `TemplateRepository`, `StatusHistoryRepository`, `ManagedListRepository`, `TelemetryRepository`
- **StorageProvider** — Central provider extended with all repository implementations; services depend on interfaces, not filesystem calls
- **`fs-helpers.ts`** — Centralized filesystem access module; the only file in the codebase that imports `fs` directly
- **Service migration** — All 10 services migrated off direct `fs` imports to use the repository interfaces
- **Extensibility** — Repository interfaces enable future storage backends (database, cloud storage) without changing service logic
---
## Infrastructure & DevOps
Production-ready deployment and development tooling.
@ -569,4 +704,4 @@ Working toward WCAG 2.1 AA compliance.
---
_Last updated: 2026-01-30 · [Back to README](../README.md)_
_Last updated: 2026-02-01 · [Back to README](../README.md)_

2
mcp/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@veritas-kanban/mcp",
"version": "1.0.0",
"version": "1.3.0",
"description": "MCP server for Veritas Kanban",
"type": "module",
"main": "./dist/index.js",

2
package.json
View file

@ -1,6 +1,6 @@
{
"name": "veritas-kanban",
"version": "1.1.0",
"version": "1.3.0",
"private": true,
"description": "Local-first task management and AI agent orchestration platform",
"author": "Brad Groux <brad@digitalmeld.io>",

2
server/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@veritas-kanban/server",
"version": "1.1.0",
"version": "1.3.0",
"private": true,
"type": "module",
"main": "./dist/index.js",

2
shared/package.json
View file

@ -1,6 +1,6 @@
{
"name": "@veritas-kanban/shared",
"version": "1.1.0",
"version": "1.3.0",
"private": true,
"type": "module",
"main": "./dist/index.js",