LedgerBoard

Your Kanban board should survive the tool that displays it.

LedgerBoard is a local-first VS Code board whose source of truth is three readable Markdown files. It adds a polished drag-and-drop workflow, generic entity palettes, conflict-safe autosave, and append-only analytics without an account, database, server, or proprietary export.

What's new in 0.2.0

• Exact, line-numbered diagnostics for card separators, multiline descriptions, mixed line endings, missing entities, malformed checkboxes, and first source/serialized differences.
• Safe Normalize BOARD.md Formatting workflow in the Command Palette and load-error screen.
• Faster initialization and multi-root discovery with parallel direct file reads, bounded probes, active-board reuse, and visible progress.
• 34 automated model, CLI, performance, and Extension Host tests, plus browser smoke coverage.

Why LedgerBoard

• Markdown stays authoritative. Review every change in Git and edit the files with any text editor.
• Local-first by design. No telemetry, cloud sync, login, or hosted service.
• Useful beyond software teams. Entities can represent projects, clients, products, teams, or workstreams.
• History without a database. Semantic create, move, update, and delete events append to a readable ledger.
• Safe around human edits. Saves stop when a Markdown buffer changed outside the board.
• Fast at runtime. The extension has no runtime package dependencies.

Quick Start

1. Open a folder in VS Code.
2. Run LedgerBoard: Initialize Board in Folder from the Command Palette.
3. Add outcomes, drag cards between columns, and configure entities and colors.
4. Commit the resulting Markdown diff when you are ready.

Initialization creates only missing files and never overwrites an existing one:

BOARD.md
KANBAN-CONFIG.md
KANBAN-HISTORY.md

Run LedgerBoard: Open Board whenever you want to return. In a multi-root workspace, LedgerBoard checks workspace roots first, validates candidates in parallel, and lets you choose when needed.

Features

Board

• Inbox, Next, Doing, Review / Blocked, and Done workflow
• Hard three-card Doing WIP limit
• P1-P4 priorities
• Search and entity/priority filters
• Responsive desktop and narrow-editor layouts
• One-second autosave with visible pending, saving, saved, and blocked states

Entities and appearance

Every card has an area linked to a generic entity. An entity can be a project, account, product, team, department, or any grouping that makes the board useful. Names and colors live in KANBAN-CONFIG.md, alongside the board title, timezone, accent, and density.

Analytics

• Current workload and completion rate
• Work by status, priority, and entity
• 7, 30, and 90-day activity ranges
• Recorded throughput and median cycle time
• Recent semantic activity from the append-only history ledger

Existing boards begin with honest baseline observations. LedgerBoard never invents old creation or completion dates.

Commands

You can also right-click a folder in Explorer and choose Initialize Board in Folder.

Markdown Contract

A card is deliberately small:

- [ ] AO-001 — Prepare the architecture review · P2 · area:project-alpha
    - **Description:** Consolidate the decisions, risks, and recommended next steps.

Status is the section containing the card. Description is the only optional detail. The full, versioned contract is in BOARD-STANDARDS.md, including a ready-to-paste prompt for coding agents that generate compatible boards.

Adjacent cards require exactly one blank physical line:

- [ ] AO-001 — First outcome · P1 · area:project-alpha
    - **Description:** First description.

- [ ] AO-002 — Second outcome · P2 · area:project-alpha
    - **Description:** Second description.

Descriptions remain one physical line. LedgerBoard reports exact card IDs and line numbers for separator, multiline-description, mixed-line-ending, and first-difference errors.

Troubleshooting

Board does not open

Run LedgerBoard: Validate Board Bundle. The error identifies the first actionable issue. If the issue is formatting-only, choose Normalize formatting. Semantic problems such as missing entities, duplicate IDs, or multiline descriptions must be corrected in Markdown.

Formatting normalization

Normalize BOARD.md Formatting previews the issues and asks for confirmation. It fixes only safe, non-semantic formatting: missing/extra blank separator lines and mixed line endings. It does not add history events or modify card content.

Large or multi-root workspaces

LedgerBoard checks root bundles before recursive discovery, probes roots in parallel, reads candidate files directly, and bounds slow filesystem probes. Common commands reuse the active board rather than rescanning the workspace.

Intentional limitations

LedgerBoard deliberately does not provide subtasks, due dates, owners, estimates, multiline descriptions, cloud synchronization, or a mobile client. Those constraints keep the Markdown contract small, deterministic, reviewable in Git, and durable without the extension.

Privacy and Trust

LedgerBoard does not collect telemetry and does not make network requests. It reads and writes only the three Markdown files in the board folder selected through the workspace. Webview scripts use a strict Content Security Policy, and every save is validated again in the extension host.

The extension supports untrusted and virtual workspaces because it never executes workspace content. As always, review source-control changes before sharing a board that may contain private information.

Requirements

• VS Code 1.103 or later
• A writable workspace for editing (read-only virtual workspaces can still be inspected)

There are no external runtime dependencies.

Development

npm ci
npm run privacy:scan
npm run test
npm run compile
npm run test:integration
npm run vsix

Press F5 to launch an Extension Development Host. The project uses TypeScript, esbuild, the VS Code test runner, and Node's built-in test runner.

Publishing is release-driven. A GitHub Release matching the package.json version triggers the Marketplace workflow; the scoped VSCE_PAT is stored only in the protected marketplace environment. A monthly credential-health workflow verifies publisher access and opens a GitHub issue before PAT expiry or Microsoft's global-PAT retirement deadline.

See CONTRIBUTING.md, SECURITY.md, and SUPPORT.md before opening a pull request or security report.

License

MIT