choda-deck 0.1.1 → 0.2.3

package/README.md

@@ -46,7 +46,11 @@ npx choda-deck
 
 Requires Node.js >= 20.
 
-## Wire it into Claude Code
+## Wire it into your MCP client
+
+choda-deck speaks stock MCP stdio — works with any client that supports the protocol. Pick the one you use:
+
+### Claude Code
 
 Add to `.claude.json` (user-level) or `.mcp.json` (project-level):
 
@@ -67,6 +71,63 @@ Add to `.claude.json` (user-level) or `.mcp.json` (project-level):
 
 Restart Claude Code → the `choda-tasks` MCP server is online.
 
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (same `mcpServers` schema as above):
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+Quit + reopen Claude Desktop. The hammer icon shows `choda-tasks` connected.
+
+### GitHub Copilot (VS Code)
+
+Create `.vscode/mcp.json` in your workspace (or add to User Settings):
+
+```json
+{
+  "servers": {
+    "choda-tasks": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "choda-deck"],
+      "env": {
+        "CHODA_DATA_DIR": "/absolute/path/to/data",
+        "CHODA_CONTENT_ROOT": "/absolute/path/to/your/notes-or-vault"
+      }
+    }
+  }
+}
+```
+
+Note: Copilot uses `servers` (not `mcpServers`) and requires `"type": "stdio"`. Reload VS Code window → tools appear in Copilot Chat under agent mode.
+
+### Other clients (Cursor, Continue, Zed, …)
+
+Any MCP-compatible client works. Use the `command` / `args` / `env` triple — drop it into whatever the client calls its MCP config block.
+
+## CLI
+
+`choda-deck` ships a read-only CLI that talks to the same SQLite store directly — no AI in the loop, no MCP roundtrip. Use it to verify state, script automations, or pipe to `jq`.
+
+```bash
+choda-deck --help                                # show all subcommands
+choda-deck task list --status TODO --json        # script-friendly
+choda-deck task show TASK-669                    # body + linked conversations
+choda-deck inbox list --project choda-deck
+choda-deck knowledge list
+choda-deck knowledge show ADR-020-embedding-architecture
+choda-deck project context choda-deck            # AI's session_start view
+choda-deck mcp serve                             # start the MCP stdio server
+```
+
+Pass `--json` to any read command for machine-readable output. Plain text is the default for humans.
+
+### Reading freshness
+
+The CLI opens SQLite in WAL mode for shared reads. While the MCP server is actively writing, a CLI read may see a snapshot from a few seconds ago — re-run after 1-2s if state looks stale. See knowledge entry `sqlite-wal-read-consistency` for details.
+
 ## Tools
 
 All tools are namespaced `mcp__choda-tasks__<name>`. Claude calls them on your behalf — you never invoke them directly.
@@ -74,13 +135,14 @@ All tools are namespaced `mcp__choda-tasks__<name>`. Claude calls them on your b
 | Domain | Tools | What it does |
 |---|---|---|
 | **Project** | `project_add`, `project_list`, `project_context` | Multi-project setup. Each project has its own task list and metadata. |
-| **Workspace** | `workspace_add`, `workspace_list`, `workspace_archive`, `workspace_remove` | Sub-scope inside a project (e.g. `frontend`, `backend`, `infra`). Knowledge entries can be scoped to a workspace. |
-| **Task** | `task_create`, `task_list`, `task_update`, `task_context`, `tasks_update_batch` | TODO → READY → IN-PROGRESS → DONE/BLOCKED. Each task has body + acceptance criteria + labels + priority. |
+| **Workspace** | `workspace_add`, `workspace_list`, `workspace_archive` | Sub-scope inside a project (e.g. `frontend`, `backend`, `infra`). Knowledge entries can be scoped to a workspace. |
+| **Task** | `task_create`, `task_list`, `task_update`, `task_context` | TODO → READY → IN-PROGRESS → DONE/BLOCKED. Each task has body + acceptance criteria + labels + priority. |
 | **Session** | `session_start`, `session_checkpoint`, `session_end`, `session_resume`, `session_list` | Bind a work session to a task. Checkpoint progress so the next session resumes with full context. |
 | **Conversation** | `conversation_open`, `conversation_add`, `conversation_decide`, `conversation_close`, `conversation_reopen`, `conversation_list`, `conversation_read`, `conversation_poll` | Structured threads (e.g. FE/BE alignment, ADR debate). `decide` logs the resolution. |
-| **Inbox** | `inbox_add`, `inbox_research`, `inbox_convert`, `inbox_ready`, `inbox_archive`, `inbox_delete`, `inbox_list`, `inbox_get`, `inbox_update` | Capture-now, decide-later. Items move `raw` → `researching` → `ready` → `converted` (to a task) or `archived`. |
-| **Knowledge** | `knowledge_create`, `knowledge_list`, `knowledge_get`, `knowledge_search`, `knowledge_update`, `knowledge_verify`, `knowledge_register_existing`, `knowledge_delete` | ADRs / decision logs with frontmatter. `refs[]` tracks implementation files + commit SHAs → staleness banner when code drifts. |
+| **Inbox** | `inbox_add`, `inbox_research`, `inbox_convert`, `inbox_ready`, `inbox_archive`, `inbox_list`, `inbox_get`, `inbox_update` | Capture-now, decide-later. Items move `raw` → `researching` → `ready` → `converted` (to a task) or `archived`. |
+| **Knowledge** | `knowledge_create`, `knowledge_list`, `knowledge_get`, `knowledge_search`, `knowledge_update`, `knowledge_verify`, `knowledge_delete` | ADRs / decision logs with frontmatter. `refs[]` tracks implementation files + commit SHAs → staleness banner when code drifts. |
 | **Backup** | `backup_create`, `backup_list`, `backup_restore` | Daily auto-backup of the SQLite DB. Manual create + restore when you need to roll back. |
+| **Ops** | `stats_report`, `cleanup_worktree_orphans` | Tool-usage telemetry (per-tool calls / error rate / dead-in-window) + worktree GC. |
 
 ## Common workflows
 
@@ -140,8 +202,12 @@ Claude : (knowledge_verify) → flags ADR-020 as potentially stale (refs SHA mis
 |---|---|---|
 | `CHODA_DATA_DIR` | _required_ | SQLite DB, artifacts, and backups directory. Created on first run. |
 | `CHODA_CONTENT_ROOT` | _optional_ | Root for knowledge / vault content lookup. |
+| `CHODA_BACKEND` | `sqlite` | Storage backend (ADR-030). `sqlite` (local file) or `postgres` (remote, k8s-friendly). |
+| `CHODA_PG_URL` | _required when `CHODA_BACKEND=postgres`_ | Postgres connection string (e.g. `postgres://user:pass@host:5432/db`). |
+| `CHODA_PG_POOL_SIZE` | `10` | Postgres connection pool max size. Tune for concurrent HTTP requests. |
+| `CHODA_EMBEDDING_PROVIDER` | `local` | `local` (transformers.js MiniLM-L6) or `noop` (disable embedding-backed search). |
 
-### Data layout
+### Data layout (SQLite)
 
 ```
 $CHODA_DATA_DIR/
@@ -150,6 +216,66 @@ $CHODA_DATA_DIR/
 └── backups/choda-deck-<date>.db  ← auto daily, retained
 ```
 
+### Postgres backend
+
+The Postgres adapter is full-feature parity with SQLite — all `mcp__choda-tasks__*` tools work against either backend. Use Postgres when running the MCP HTTP transport in k8s (ADR-026 + ADR-030).
+
+**Local dev** with the shipped `docker-compose.yml`:
+
+```bash
+docker compose up -d                             # boots pgvector/pgvector:pg16 on :5432
+export CHODA_BACKEND=postgres
+export CHODA_PG_URL="postgres://choda:choda@localhost:5432/choda"
+pnpm run mcp:http                                # schema migrates on first connect
+```
+
+**k8s** — minimal `Deployment` + `Secret` shape:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata: { name: choda-pg }
+type: Opaque
+stringData:
+  CHODA_PG_URL: postgres://choda:CHANGEME@choda-pg.default.svc.cluster.local:5432/choda
+  MCP_HTTP_TOKEN: REPLACE_WITH_BASE64URL_32_BYTES
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata: { name: choda-deck }
+spec:
+  replicas: 1
+  template:
+    spec:
+      containers:
+        - name: choda
+          image: ghcr.io/your-org/choda-deck:latest
+          env:
+            - { name: CHODA_BACKEND,  value: postgres }
+            - { name: MCP_TRANSPORT,  value: http }
+            - { name: MCP_HTTP_BIND,  value: 0.0.0.0 }
+          envFrom:
+            - secretRef: { name: choda-pg }
+          ports:
+            - containerPort: 7337
+          readinessProbe:
+            httpGet: { path: /healthz, port: 7337 }
+```
+
+Bring your own Postgres (Cloud SQL, RDS, managed) or run a sidecar `StatefulSet` with the `pgvector/pgvector:pg16` image. Migrations and the pgvector extension setup are idempotent — they run automatically inside `initializeAsync()` on every boot.
+
+**Migration from existing SQLite data** — one-shot script:
+
+```bash
+CHODA_PG_URL="postgres://choda:choda@localhost:5432/choda" \
+  node scripts/migrate-sqlite-to-postgres.mjs \
+    --sqlite $CHODA_DATA_DIR/database/choda-deck.db [--dry-run]
+```
+
+The script is idempotent (skips tables that already have rows; pass `--force` to wipe + reload). Embedding vectors are NOT copied — re-run `scripts/backfill-embeddings.mjs` against the Postgres backend after migration to rebuild them.
+
+The cross-device pending-ops sync engine (ADR-030 §2) is **not** in this release — laptop ↔ remote MCP today is "one backend at a time," not a live sync. Pick `CHODA_BACKEND` per process.
+
 ## Architecture
 
 - **SQLite** (`better-sqlite3`) — single source of truth, file-based, no daemon
@@ -161,7 +287,7 @@ See [`docs/architecture.md`](https://github.com/butterngo/choda-deck/blob/main/d
 
 ## Status
 
-`0.1.0` — early, dogfooded daily by the author. API may move before `1.0`. Issues + PRs welcome.
+`0.2.0` — early, dogfooded daily by the author. API may move before `1.0`. Issues + PRs welcome.
 
 ## License
 

package/dist/mcp-rules.md

@@ -0,0 +1,170 @@
+# MCP Rules
+
+Behavioral contract for MCP tools (session + conversation). Edit this file to update compliance rules — no MCP restart needed. Each `## On <tool_name>` section is loaded by the matching tool handler and injected into its response.
+
+## On session_start
+
+`session_start` now requires a `taskId` — the task is bound to the session at creation and auto-set to IN-PROGRESS.
+
+Before calling `session_start`:
+
+1. Call `task_list` (or `roadmap`) to show the user available tasks, grouped by priority (high → medium → low).
+2. Wait for the user to pick a task. Do not guess.
+3. Call `session_start({ projectId, taskId, workspaceId?, cwd? })`. Always pass `cwd` (current shell directory) so the MCP can auto-detect `workspaceId` for projects with registered workspaces — the MCP server's own cwd is fixed and cannot be inferred.
+4. Echo the `lastSession` block to the user verbatim — resume point, decisions, loose ends, tasks updated, commits. Do not summarize.
+5. Create a feature branch for the task:
+   - Branch name: `feat/<task-id>-<short-slug>` (e.g. `feat/task-564-session-conv-ui`)
+   - Required: `git checkout -b feat/<task-id>-<short-slug>`
+   - Optional (if user wants parallel worktree): detect repo root via `git rev-parse --show-toplevel`, then `git worktree add <repo-root>.worktrees/<slug> -b feat/<task-id>-<short-slug>`
+   - Ask the user whether they want a worktree or just a branch before proceeding.
+
+Workspace resolution order (when project has ≥1 workspace registered):
+- explicit `workspaceId` wins
+- else `cwd` is matched against registered workspace cwds (longest prefix wins for nested repos)
+- else MCP throws — pick a workspace explicitly or call `workspace_add`
+
+If the project has no workspaces registered, `workspaceId` may be `null` (backward-compatible).
+
+Blocking conditions (MCP returns an error):
+- Task not found
+- Task already `DONE` — reopen it with `task_update` first
+- Task already bound to another active session — end that session first
+- Project has workspaces but neither `workspaceId` nor a matching `cwd` was provided
+
+## On session_checkpoint
+
+`session_checkpoint` snapshots progress on an active session **without ending it**. Overwrite-in-place — each call replaces the previous checkpoint.
+
+When to checkpoint:
+
+- Before risky operations (rebase, force-push, schema migration, large refactor)
+- Before context window compaction (when conversation grows long)
+- Every ~30 minutes of active work, or after a meaningful sub-step
+- When pausing work mid-task (lunch, meeting) — so a future `session_resume` recovers state cleanly
+
+Required field:
+
+- **resumePoint** — one sentence describing exactly where you stopped and what to pick up next
+
+Recommended fields (include whichever apply):
+
+- **lastConversationId** — most recent conversation touched (resume context)
+- **dirtyFiles** — files edited but not yet committed (so resume knows what's in flight)
+- **lastCommit** — last commit SHA written this session (resume git position)
+- **notes** — free-form context that matters for resume (decisions made, dead ends ruled out)
+
+Do not call `session_checkpoint` as a substitute for `session_end`. Checkpoint = pause; end = finalize + handoff.
+
+## On session_resume
+
+`session_resume` returns the session row, last checkpoint, linked conversations, and active context sources. Use after crash, restart, or context compaction — not as a way to spawn a new session for the same task.
+
+After calling `session_resume`:
+
+1. **Echo the checkpoint summary verbatim** — `resumePoint`, `notes`, `dirtyFiles`, `lastCommit`, `lastConversationId`. Do not summarize. Butter needs the same view the prior session had.
+2. **Confirm task binding** — name the `taskId` and current status. If the task is no longer IN-PROGRESS, surface the discrepancy before proceeding.
+3. **Resume from `resumePoint`** — pick up the exact next step. Do not re-plan from scratch.
+4. **Do not call `session_start`** — resume reactivates the existing session; starting a new one orphans the checkpoint and creates duplicate state.
+
+If no checkpoint exists (resumed session was never checkpointed), say so explicitly and ask Butter where to pick up before continuing.
+
+## On session_end
+
+When preparing the session_end payload, always include:
+
+- **resumePoint** (required) — one sentence describing where you stopped and what the next session should pick up.
+- **tasksUpdated** (required if session had a taskId) — list of task ids and their new status.
+- **decisions** — architectural or implementation decisions made this session. Explicit > implicit.
+- **looseEnds** — genuine ideas that need future research. NOT a catch-all dump. See classification rule below.
+- **commits** — commit SHAs + short message if commits were made.
+
+Never end a session with only resumePoint. If the session was trivial (read-only), explicitly note "no changes" in resumePoint or notes.
+
+### Classify each loose end BEFORE writing it
+
+Every candidate loose end falls into exactly one of 3 buckets. Pick the bucket first, then route accordingly:
+
+1. **Action item** (has clear owner + acceptance criteria) → call `task_create` directly with status=TODO or READY. Do NOT put it in `looseEnds`. Examples: "PR #5 awaiting merge — on merge delete branch", "companion repo 2 commits ahead — needs push".
+2. **Dirty-state observation** (untracked file, stale branch, cosmetic shell handle, lingering process) → put it in `notes` field or the commit message. Do NOT put it in `looseEnds`. Examples: "stale worktree at .worktrees/foo", "Windows file handle on dist/", "untracked spike notes in /tmp".
+3. **Genuine idea needing research** (open question, design uncertainty, "should we…?") → `looseEnds` (this is the legitimate use). Each entry: 1 line, concrete, no acceptance criteria yet. Example: "investigate whether prewarm cache can survive worktree switch".
+
+`looseEnds` are auto-converted to inbox entries (status=raw) under the session's project — one entry per item, tagged with the source session/task ID. Butter reviews the inbox in `/daily` and decides which deserve `inbox_convert` → task. If you find yourself dumping action items or observations into `looseEnds`, you skipped step 1 — go back and classify.
+
+### Structured summary payload (ADR-028)
+
+`session_end` accepts an optional typed `summary` field. When provided, the server writes one `session_events` row (`event_type='observation'`, `payload.kind='session_summary'`) atomic with the session close. Use it on real implementation sessions — TASK-846 auto-recall and the Dashboard Sessions tab both read this shape.
+
+**Required (FE base):**
+
+| Field | Type | Notes |
+|---|---|---|
+| `summary` | `string` | One paragraph: what shipped, what stalled, what's next |
+| `tasksDone` | `string[]` | Task IDs marked DONE in this session |
+| `tasksCreated` | `string[]` | Task IDs created in this session |
+| `tasksCancelled` | `string[]` | Task IDs cancelled in this session |
+| `commits` | `string[]` | Format: `"<short-hash> <task-id> <subject>"` |
+| `conversations` | `string[]` | Conversation IDs touched / decided |
+| `openItems` | `string[]` | Carry-forward items — distinct from `looseEnds` (action items already filed as tasks) |
+
+**AI-optional — server auto-fills from channels 1+2 (TASK-913):**
+
+| Field | Type | Notes |
+|---|---|---|
+| `filesChanged` | `string[]?` | Format: `"<path> (<what changed>)"`. Omit → server appends `"<path> (+N, -M)"` per unique path from `kind='file_modified'` events (channel 1). AI entries kept verbatim; only unseen paths appended. |
+| `acCoverage` | `Record<taskId, string>?` | e.g. `"TASK-X": "5/5 verified (...). 0 deferred."`. Omit → server emits `"N/M verified (<evidence>)"` derived from `kind='ac_check'` events (channel 2), where `M = findAcItems(task.body).length` at session-end. AI entry kept verbatim + ` + K auto-detected` suffix added when events exist. |
+
+**Merge rule:** AI input wins — your judgment narrative trumps mechanical aggregation. The aggregator only fills gaps; it never overwrites a value you provided.
+
+**Optional (BE extension):**
+
+`tasksShipped: Array<{id, title, commits, files, tests, confidence}>`, `tasksNotDone: Array<{id, reason}>`, `testCoverageSummary: string`, `outstandingRisks: string[]`, `branchState: string`.
+
+**Canonical example** (mirrors EVT-1779256867162-5 — SESSION-1779246110272-1, TASK-800 PIM FE):
+
+```json
+{
+  "summary": "TASK-800 shipped: PIM FE list-screen virtualization landed; PR #482 squash-merged. Two follow-ups carried forward (filter chip a11y, prefetch on hover).",
+  "tasksDone": ["TASK-800"],
+  "tasksCreated": ["TASK-805", "TASK-806"],
+  "tasksCancelled": [],
+  "commits": ["a1b2c3d TASK-800 feat(pim-fe): virtualized list with row prefetch"],
+  "filesChanged": [
+    "src/pim/list/VirtualList.tsx (new — react-window wrapper)",
+    "src/pim/list/list-page.tsx (swap table → VirtualList)"
+  ],
+  "acCoverage": {
+    "TASK-800": "6/6 verified (lint+vitest+build+manual smoke @ 10k rows). 0 deferred."
+  },
+  "conversations": ["CONV-1779246111-1"],
+  "openItems": [
+    "Filter chip a11y — screenreader announces stale label after clear (TASK-805)",
+    "Row prefetch on hover — current eager prefetch wastes ~30% requests (TASK-806)"
+  ]
+}
+```
+
+**Narrative-only example** (relies on the channels 1+2 aggregator to fill `filesChanged` + `acCoverage` — minimum viable payload for an agent that has been calling `ac_check` and has the file-edit hook installed):
+
+```json
+{
+  "summary": "TASK-913 shipped: session-summary aggregator wires channels 1+2 into session_end. Narrative-only payloads now produce fully populated stored summaries.",
+  "tasksDone": ["TASK-913"],
+  "tasksCreated": [],
+  "tasksCancelled": [],
+  "commits": ["d4d4d4d TASK-913 feat: session-summary aggregator"],
+  "conversations": [],
+  "openItems": []
+}
+```
+
+Stored payload `filesChanged` ends up `["src/core/domain/lifecycle/session-lifecycle-service.ts (+62, -3)", …]` and `acCoverage` `{"TASK-913": "5/5 verified (lint exits 0; vitest 35/35 …)"}` — both server-derived.
+
+**Validation:** invalid payload → 400 from MCP, session is NOT closed. Omitting `summary` entirely is fully backward compatible (no observation row created, no error). Schema lives at `src/adapters/mcp/mcp-tools/session-tools.ts` (`sessionSummarySchema`).
+
+## On conversation_read
+
+- Read first. If your name is missing from `readBy` on any message, process those messages and reflect them in your reply.
+- State a position. Each turn must be one of: `signoff`, `propose_rewrite` (and rewrite the summary), `abstain_blocked` (name the blocker), `needs_clarification` (ask the question).
+- One live position. Your latest message supersedes your earlier ones — don't argue across messages; rewrite the summary.
+- Stay short. 1500-char cap is enforced. Long content goes to `decisionSummary`, a knowledge entry, or a linked artifact.
+- Decisions own actions. If follow-up work exists, add it to `actions[]` with `assignee` and `linkedTaskId`.