feat(US-1600): Complete SOP Sprint + fix GH-86 & GH-87

Documentation (8 new files in docs/): - GETTING-STARTED.md: 5-min quickstart, BoardKit insights, sanity checks - SOP-agent-task-workflow.md: Full lifecycle (claim → work → complete) - SOP-sprint-planning.md: Epic → sprint → task hierarchy + estimation - SOP-multi-agent-orchestration.md: PM + worker roles, handoff patterns - SOP-cross-model-code-review.md: Claude ↔ GPT gate, checklist, RF-002 ref - BEST-PRACTICES.md: 10 DOs + 10 DON'Ts based on real usage - EXAMPLES-agent-workflows.md: 6 copy/pasteable recipes (feature, bug fix, docs, audit, content, research) - TIPS-AND-TRICKS.md: CLI shortcuts, keyboard shortcuts, integrations (MCP, git worktrees, Obsidian) - README.md: Added 'Documentation Map' linking all new docs Bug Fixes: - fix(GH-86): BulkActionsBar now handles archive errors gracefully * Per-task error tracking (replaces Promise.all) * Toast notifications on success/partial/failure * Logs individual failures to console - fix(GH-87): Sidebar metrics now stay in sync with board state * Invalidate metrics cache when task status changes * Prevents up-to-30s lag in sidebar counts * Preserves timer state during mutations Scripts: - scripts/dev-clean.sh: Added explicit pnpm path resolution for launchd - scripts/dev-watchdog.sh: Fixed restart storm prevention + pnpm path BREAKING: None TESTING: - Manual: Bulk archive Done column tasks, verify toasts appear - Manual: Move tasks between columns, verify sidebar counts update <2s - Unit: Consider regression tests for metrics invalidation
2026-08-28 02:44:59 +00:00 · 2026-02-04 08:18:01 -06:00 · 2026-02-04 08:18:01 -06:00 · eeb11ba219
commit eeb11ba219
parent 4936a64b12
13 changed files with 1064 additions and 5 deletions
--- a/README.md
+++ b/README.md
@ -59,6 +59,17 @@ Open [http://localhost:3000](http://localhost:3000) — that's it. The board aut

 ---

+## 📚 Documentation Map
+
+- [Getting Started Guide](docs/GETTING-STARTED.md) — zero ➝ agent-ready in 5 minutes, plus sanity checks and prompt registry tips.
+- [Agent Task Workflow SOP](docs/SOP-agent-task-workflow.md) — lifecycle, API/CLI snippets, prompts.
+- [Sprint Planning SOP](docs/SOP-sprint-planning.md) — epic → sprint → task breakdown.
+- [Multi-Agent Orchestration](docs/SOP-multi-agent-orchestration.md) — PM + worker handoffs.
+- [Cross-Model Code Review](docs/SOP-cross-model-code-review.md) — enforce Claude ↔ GPT reviews.
+- [Best Practices](docs/BEST-PRACTICES.md) & [Tips + Tricks](docs/TIPS-AND-TRICKS.md) — patterns, shortcuts, integrations.
+- [Real-World Examples](docs/EXAMPLES-agent-workflows.md) — copy/pasteable agent recipes.
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — deeper diagnostics when things wobble.
+
 ## ⚠️ Agentic AI Safety

 > [!CAUTION]
--- a/docs/BEST-PRACTICES.md
+++ b/docs/BEST-PRACTICES.md
@ -0,0 +1,75 @@
+# Best Practices & Anti-Patterns
+
+Codify what works (and what burns us) when running Veritas Kanban with humans + AI agents.
+
+---
+
+## Do This
+
+1. **Always track time**
+   - Start timers with `vk begin` the moment you pick up a task.
+   - If you forgot, add a manual entry with reason. Time data fuels estimation and billing.
+
+2. **Use subtasks as living checklists**
+   - Break work into 3–8 subtasks.
+   - Mark them complete as you progress; unfinished subtasks make blockers obvious.
+
+3. **Write acceptance criteria inside the task description**
+   - Bullet list or checklist. Agents need crisp definitions of done.
+
+4. **Post completion summaries + links**
+   - Final comment should include what changed, where to find artifacts, and next steps.
+
+5. **Keep tasks atomic**
+   - One deliverable per task. If work spans >3 days or mixes unrelated goals, split it.
+
+6. **Update SOP files after every lesson**
+   - Mistake → update AGENTS.md/CLAUDE.md + Lessons Learned field.
+
+7. **Respect cross-model review**
+   - Treat it like CI. No code ships without the opposite model’s signoff.
+
+8. **Mirror important artifacts to Brain/knowledge base**
+   - Use `scripts/brain-write.sh` or equivalent so humans can find deliverables later.
+
+9. **Use Agent Status + comments for visibility**
+   - Set `vk agent working` when you start; leave concise updates in comments instead of DM spam.
+
+10. **Archive aggressively**
+    - Done column should stay lean. Use multi-select + archive (bug tracked separately) at sprint end.
+
+---
+
+## Don’t Do This
+
+1. **Tasks without acceptance criteria**
+   - Leads to rework and ambiguous reviews.
+
+2. **Skipping time tracking**
+   - “It was quick” is not data. Even 5-minute fixes get tracked.
+
+3. **Giant grab-bag tasks**
+   - “Implement feature + write docs + shoot video” belongs in separate tasks.
+
+4. **Auto-piloting agents without supervision**
+   - Always read summaries, review diffs, enforce cross-model review.
+
+5. **Letting prompts drift**
+   - Keep prompt registry updated or agents will regress.
+
+6. **Leaving example tasks in production boards**
+   - Clear the seed tasks before real work to avoid confusion.
+
+7. **Treating planning as a board status**
+   - Planning is a checklist/subtask, not `TaskStatus`. Valid statuses: todo, in-progress, blocked, done.
+
+8. **Storing secrets in tasks**
+   - Use vault/secret manager references, never raw credentials.
+
+9. **Ignoring Lessons Learned**
+   - If you uncover a process flaw and don’t log it, you’ll repeat it next sprint.
+
+10. **Copy/pasting unvetted external code**
+    - Run security review (see RF-002) and cite sources.
+
+Stick to these rules and the board stays trustworthy even with dozens of agents in parallel.
--- a/docs/EXAMPLES-agent-workflows.md
+++ b/docs/EXAMPLES-agent-workflows.md
@ -0,0 +1,94 @@
+# Real-World Agent Workflow Examples
+
+Steal these end-to-end flows when building your own automations. Each example shows the goal, prompts, API/CLI calls, and outputs we expect.
+
+---
+
+## 1. Feature Development Sprint (BrainMeld PRD excerpt)
+
+**Goal:** Build "Lessons Learned" field.
+
+1. **Create task**
+   ```bash
+   vk create "Feature: Lessons Learned field" --project veritas-kanban --type feature --priority medium
+   ```
+2. **Prompt (worker)**
+   ```
+   Implement markdown lessonsLearned field on tasks (UI + API). Include migration + docs. Cross-model review required.
+   ```
+3. **Workflow**
+   - `vk begin <id>`
+   - Implement server -> shared -> web changes
+   - Update docs + tests
+   - `vk done <id> "Added lessons learned field"`
+4. **Outputs**
+   - Task summary with PR link
+   - Lessons Learned comment describing future usage
+
+---
+
+## 2. Bug Fix (Archive bulk action)
+
+**Goal:** Sprint archive button fails.
+
+1. Create bug task referencing GitHub Issue #86.
+2. Subtasks:
+   - Reproduce in dev
+   - Inspect network requests
+   - Patch bulk archive handler
+   - Add regression test (Playwright)
+3. CLI flow: `vk begin`, fix, `vk done "Bulk archive now calls API"`
+4. Cross-model review ensures UI + API parity.
+
+---
+
+## 3. Documentation Update
+
+**Goal:** Add sanity checks to Getting Started.
+
+1. Task description includes sections to cover (API, UI, agent pickup).
+2. Agent edits `docs/GETTING-STARTED.md` + `docs/TROUBLESHOOTING.md` references.
+3. Completion summary links to diff + screenshot placeholders.
+
+---
+
+## 4. Security Audit (RF-002 style)
+
+**Goal:** Run cross-model audit on repo.
+
+1. Task -> `type=security`, `project=veritas-kanban`.
+2. Subtasks: scope, run Codex audit, run Claude review, compile findings, create issues.
+3. Agents spawn using research prompt template, save results to `refactoring/rf-002/*`.
+4. Deliverables: Markdown report, HTML deck, GitHub issues.
+
+---
+
+## 5. Content Production (Podcast clip → LinkedIn post)
+
+1. Task `type=content` with acceptance criteria (summary, caption, schedule time).
+2. Agent fetches transcript, writes summary, drafts LinkedIn copy, saves assets to `projects/start-small-think-big/...`.
+3. Completion summary includes copy + asset path; lessons learned capture platform insights.
+
+---
+
+## 6. Research & Report (Champions)
+
+1. Task `type=research`, project `social`, sprint `CHAMP-02`.
+2. Prompt includes dossier template, required sources, HTML deck requirement.
+3. Agent workflow: gather sources, write Markdown, generate HTML via script, `brain-write.sh` to mirror.
+4. Final comment: TL;DR + links to both artifacts.
+
+---
+
+## Pattern to Copy
+
+For any workflow:
+
+1. **Task** with crystal-clear done definition.
+2. **Prompt** stored in registry.
+3. **API/CLI** calls scripted (vk begin/done, time tracking, status updates).
+4. **Artifacts** saved to predictable paths and mirrored to Brain/engram if needed.
+5. **Cross-model review** if code/critical.
+6. **Lessons learned** field updated for systemic knowledge.
+
+Use these recipes as seeds for your own automation playbooks.
--- a/docs/GETTING-STARTED.md
+++ b/docs/GETTING-STARTED.md
@ -0,0 +1,266 @@
+# Getting Started with Veritas Kanban
+
+> **Credit:** This guide exists because **Neal (@nealmummau)** asked how to get Veritas Kanban working with AI agents in under five minutes. Thank you for pushing us to document the real workflow.
+
+Whether you are standing up the board for yourself or for a fleet of agents, this guide walks you from zero ➝ working board ➝ agents picking up work. Each section is short, copy/paste friendly, and mirrors how we run Veritas Kanban internally.
+
+---
+
+## Table of Contents
+
+1. [Prerequisites (30 seconds)](#prerequisites-30-seconds)
+2. [Installation & Setup Wizard (manual today, guided tomorrow)](#installation--setup-wizard-manual-today-guided-tomorrow)
+3. [Create Your First Task (UI path)](#create-your-first-task-ui-path)
+4. [Create Your First Task (API/CLI path)](#create-your-first-task-apicli-path)
+5. [Connect an Agent + Agent Pickup Checklist](#connect-an-agent--agent-pickup-checklist)
+6. [Sanity Checks & Quick Fixes](#sanity-checks--quick-fixes)
+7. [Shared Resources & Prompt Registry](#shared-resources--prompt-registry)
+8. [Documentation Freshness & Repo Rules](#documentation-freshness--repo-rules)
+9. [Multi-Repo / Multi-Agent Notes](#multi-repo--multi-agent-notes)
+10. [OpenClaw Browser Relay (Optional but recommended)](#openclaw-browser-relay-optional-but-recommended)
+11. [What’s Next?](#whats-next)
+
+---
+
+## Prerequisites (30 seconds)
+
+| What              | Command            | Notes                                              |
+| ----------------- | ------------------ | -------------------------------------------------- |
+| Node.js           | `node -v`          | Requires **22+**. Install via Volta/nvm if older.  |
+| pnpm              | `pnpm -v`          | Requires **9+**. `npm install -g pnpm` if missing. |
+| Git               | `git --version`    | Any current version works.                         |
+| (Optional) Docker | `docker --version` | Needed only if you prefer containers.              |
+
+That’s it. No database, no extra services.
+
+---
+
+## Installation & Setup Wizard (manual today, guided tomorrow)
+
+A scripted setup wizard (`vk setup`) is on the roadmap. Until it ships, follow the manual wizard below (same phases you’ll see in the UI later):
+
+### 1. Clone & install
+
+```bash
+git clone https://github.com/BradGroux/veritas-kanban.git
+cd veritas-kanban
+pnpm install
+```
+
+### 2. Configure server
+
+a. Copy the sample env
+
+```bash
+cp server/.env.example server/.env
+```
+
+b. Edit the new file:
+
+- `VERITAS_ADMIN_KEY` → 32+ chars (use `node -e "console.log(crypto.randomBytes(32).toString('hex'))"`)
+- `VERITAS_AUTH_ENABLED=true` (default)
+- `VERITAS_AUTH_LOCALHOST_BYPASS=true` to avoid auth friction locally
+- Optional: set `HOST=127.0.0.1` (avoids proxy ambiguity)
+
+### 3. Start the dev stack
+
+```bash
+pnpm dev
+```
+
+Web boots on **3000**, API on **3001**. First boot seeds demo tasks so you have something to look at.
+
+![Dev stack running](../assets/demo-overview.gif)
+
+### 4. Run the in-app setup
+
+Visit [http://localhost:3000](http://localhost:3000) → follow the onboarding form:
+
+- Create your admin password
+- Save the recovery key (seriously; it’s the only way to regain access)
+- Log in and confirm you can see the seeded board
+
+> 🧙 **Setup Wizard roadmap:** v1.5 will ship an interactive `vk setup` CLI that steps through these same actions, validates ports, and optionally provisions starter API keys.
+
+---
+
+## Create Your First Task (UI path)
+
+1. Click **New Task** on the board.
+2. Fill title, description (Markdown), pick a type + priority.
+3. Optional: assign a sprint/project.
+4. Hit **Create** and watch it appear in **Todo**.
+5. Drag it to **In Progress** to feel the flow.
+
+![Creating a task via UI](../assets/demo-task.gif)
+
+> Need a clean slate? Remove the example tasks: `rm tasks/active/task_example_*.md`
+
+---
+
+## Create Your First Task (API/CLI path)
+
+### REST call (curl)
+
+```bash
+curl -X POST http://localhost:3001/api/tasks \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: <YOUR_ADMIN_KEY>" \
+  -d '{
+    "title": "Wire up MCP server",
+    "description": "Create CLI + MCP parity",
+    "type": "feature",
+    "priority": "high"
+  }'
+```
+
+### CLI (after `cd cli && npm link`)
+
+```bash
+vk create "Wire up MCP server" --type feature --priority high
+vk list --status todo
+```
+
+CLI commands fully mirror the API and are the fastest way to script agent workflows.
+
+![CLI workflow demo](../assets/demo-drag_drop.gif)
+
+---
+
+## Connect an Agent + Agent Pickup Checklist
+
+Agents interact through HTTP + WebSocket; nothing is hard-coded to a particular provider. Follow this checklist to verify they can pick up work:
+
+1. **Create an agent API key** in `server/.env`:
+   ```
+   VERITAS_API_KEYS=my-agent:super-secret-key:agent,ops:another-key:admin
+   ```
+2. **Restart** `pnpm dev` so the key loads.
+3. **Create an agent request** (UI → Start Agent) or drop a JSON file in `.veritas-kanban/agent-requests/`.
+4. **Watch pending agents** in the UI or via CLI:
+   ```bash
+   vk agents:pending
+   ```
+5. **Agent workflow** (example prompt to OpenClaw):
+   ```
+   Hey Veritas, pick up task <ID>. Set status to in-progress, start the timer, do the work, then call `vk done <id> "summary"` when finished. Use cross-model review if you wrote code.
+   ```
+6. **Agent completion**
+   - Verify `tasks/active/...` reflects status/time tracking
+   - Check `.veritas-kanban/logs/agents.log` for run details
+   - Confirm UI Agent Status indicator flips back to **Idle**
+
+![Agent status indicator](../assets/demo-task.gif)
+
+> **Automation tip:** Keep a `prompts/` folder (see below) so agents get consistent instructions for sprint planning, reviews, research, etc.
+
+---
+
+## Sanity Checks & Quick Fixes
+
+These cover the “something feels off” moments before you deep-dive logs.
+
+### 1. API health (up in <1s)
+
+```bash
+curl -s http://localhost:3001/api/health | jq
+```
+
+Expect `{ "ok": true, "service": "veritas-kanban", ... }`. If the call hangs or returns HTML, something else is on the port.
+
+### 2. UI health
+
+- Browser hard refresh (`Cmd/Ctrl + Shift + R`)
+- If blank, open devtools → Console for errors.
+- Verify WebSocket indicator (top right) shows **Connected**; if not, check proxies/CORS.
+
+### 3. Agent pickup sanity
+
+- `.veritas-kanban/agent-requests/` should have JSON per request. If files accumulate, agents are not acknowledging them.
+- `vk agents:pending` returning nothing while UI shows pending usually means API key mismatch; regenerate and restart.
+
+### 4. Common failure modes & instant fixes
+
+| Symptom                     | Quick Fix                                                     |
+| --------------------------- | ------------------------------------------------------------- |
+| Ports collide / UI hung     | `pnpm dev:clean`                                              |
+| Health endpoint returns 404 | Wrong project running on 3001 (restart)                       |
+| Auth spamming rate limit    | Ensure request IP is `127.0.0.1` or increase limiter          |
+| Agents “never pick up”      | Verify API key role `agent`, check firewall/Docker networking |
+
+For deeper debugging see [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
+---
+
+## Shared Resources & Prompt Registry
+
+BoardKit Orchestrator inspired us here: keep prompts, skills, and guidelines in one place so every repo/agent stays in sync.
+
+**Until first-class registry lands in v1.5, do this manually:**
+
+1. Create `shared/prompt-registry/` at the repo root (git-tracked).
+2. Add Markdown files per workflow, e.g.:
+   - `shared/prompt-registry/sprint-planning.md`
+   - `shared/prompt-registry/code-review.md`
+   - `shared/prompt-registry/research-report.md`
+3. Reference them inside tasks (`See prompt: shared/prompt-registry/...`).
+4. When spawning agents (OpenClaw `sessions_spawn`), paste the relevant prompt so the run is reproducible.
+
+> **Future state:** US-1611 will move this into `.veritas-kanban/templates/prompts.json` with UI + API surfaces. Document your prompts now so migration is painless later.
+
+---
+
+## Documentation Freshness & Repo Rules
+
+Stale docs = hallucinating AI. Keep these files current:
+
+| File                           | Purpose                                                        |
+| ------------------------------ | -------------------------------------------------------------- |
+| `AGENTS.md`                    | Personality, escalation rules, cross-model review requirement. |
+| `SOUL.md`                      | “Who are we?” — tone/voice used by agents.                     |
+| `CLAUDE.md` / `GPT.md`         | Model-specific guardrails or lessons learned.                  |
+| `docs/BEST-PRACTICES.md` (new) | Patterns and anti-patterns all agents follow.                  |
+
+**Cadence:**
+
+- Update immediately after a mistake or new learning.
+- Mirror to Brain/knowledge base if you use one (see `scripts/brain-write.sh`).
+- During sprint closure, skim the “Lessons Learned” field on each task and propagate anything evergreen into AGENTS/CLAUDE.
+
+---
+
+## Multi-Repo / Multi-Agent Notes
+
+Running multiple projects or repos with the same agent pool? Borrow BoardKit’s approach:
+
+- Keep shared assets (skills, prompts, SOPs) under a top-level `shared/` folder.
+- For each repo, mount/symlink only what you need (manual today; native support in US-1611).
+- Use consistent naming for agent API keys so dashboards stay readable (`project-agent-name`).
+- Record sub-agent usage with `vk agent sub-agent <count>` so the Agent Status sidebar matches reality.
+
+---
+
+## OpenClaw Browser Relay (Optional but Recommended)
+
+For auth-required workflows (LinkedIn research, dashboards behind Okta, etc.) you’ll want OpenClaw’s Browser Relay:
+
+1. Install the extension + helper from the [OpenClaw docs](https://github.com/openclaw/openclaw).
+2. Launch the relay; attach your tab.
+3. Agents can now run headless instructions through your actual browser session while respecting your credentials.
+
+This is invaluable for Champions-style research tasks or anything needing a real login flow.
+
+---
+
+## What’s Next?
+
+1. Read the SOPs:
+   - [Agent Task Workflow](SOP-agent-task-workflow.md)
+   - [Sprint Planning with AI Agents](SOP-sprint-planning.md)
+   - [Multi-Agent Orchestration](SOP-multi-agent-orchestration.md)
+   - [Cross-Model Code Review](SOP-cross-model-code-review.md)
+2. Align on [Best Practices](BEST-PRACTICES.md) & [Tips + Tricks](TIPS-AND-TRICKS.md).
+3. Browse [Real-world Examples](EXAMPLES-agent-workflows.md) and steal the prompts.
+4. Keep `docs/TROUBLESHOOTING.md` handy for deeper diagnostics.
+
+You now have a board, agents that can pick up work, and a safety net when things wobble. Go ship something.
--- a/docs/SOP-agent-task-workflow.md
+++ b/docs/SOP-agent-task-workflow.md
@ -0,0 +1,120 @@
+# SOP: Agent Task Workflow (Create → Work → Complete)
+
+Use this playbook anytime an agent (human or LLM) takes a task from **todo** to **done**. It standardizes status changes, time tracking, summaries, and ensures telemetry stays usable.
+
+---
+
+## Roles
+
+| Role               | Responsibilities                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------- |
+| **Human / PM**     | Defines clear task + acceptance criteria, reviews results, enforces cross-model review. |
+| **Worker Agent**   | Picks up a task, updates status/time, posts results, flags blockers.                    |
+| **Reviewer Agent** | Opposite-model reviewer for code or high-risk work (see Cross-Model SOP).               |
+
+---
+
+## Lifecycle Overview
+
+| Stage       | Action                                                                                            | Required?   |
+| ----------- | ------------------------------------------------------------------------------------------------- | ----------- |
+| 0. Intake   | Task created with clear title, description, acceptance criteria, type, project, sprint.           | ✅          |
+| 1. Claim    | Agent sets status `in-progress`, starts timer, sets Agent Status → working.                       | ✅          |
+| 2. Work     | Agent executes subtasks; marks subtasks complete as it goes.                                      | ✅          |
+| 3. Update   | Post intermediate comment(s) or blockers; set status `blocked` if waiting on human.               | As needed   |
+| 4. Complete | Stop timer, set status `done`, provide completion summary + attachments, capture lessons learned. | ✅          |
+| 5. Review   | Trigger cross-model review if code touched or risk level ≥ medium.                                | ✅ for code |
+
+---
+
+## API Flow
+
+```bash
+# Claim
+curl -X PATCH http://localhost:3001/api/tasks/<id> \
+  -H "Authorization: Bearer <agent-key>" \
+  -H "Content-Type: application/json" \
+  -d '{"status":"in-progress"}'
+
+curl -X POST http://localhost:3001/api/tasks/<id>/time/start \
+  -H "Authorization: Bearer <agent-key>"
+
+curl -X POST http://localhost:3001/api/agent/status \
+  -H "Authorization: Bearer <agent-key>" \
+  -d '{"status":"working","taskId":"<id>","taskTitle":"Fix CLI"}'
+
+# Update (optional comment)
+curl -X POST http://localhost:3001/api/tasks/<id>/comments \
+  -H "Authorization: Bearer <agent-key>" \
+  -d '{"text":"Blocked on dependency"}'
+
+# Complete
+curl -X POST http://localhost:3001/api/tasks/<id>/time/stop \
+  -H "Authorization: Bearer <agent-key>"
+
+curl -X PATCH http://localhost:3001/api/tasks/<id> \
+  -H "Authorization: Bearer <agent-key>" \
+  -d '{
+    "status":"done",
+    "completionSummary":"Added OAuth + tests",
+    "lessonsLearned":"Always stub the provider"
+  }'
+```
+
+---
+
+## CLI Flow (fast path)
+
+```bash
+vk begin <id>                         # sets in-progress, starts timer, agent status → working
+# ...do the work...
+vk done <id> "Added OAuth + regression test"
+```
+
+Optional helpers:
+
+```bash
+vk block <id> "Waiting on design"     # sets blocked + comment
+vk unblock <id>                       # returns to in-progress, restarts timer
+vk time show <id>                     # verify time entries before completing
+```
+
+---
+
+## Prompt Template (Worker Agent)
+
+```
+Task: <ID> — <Title>
+URL: http://localhost:3000/task/<ID>
+
+1. Set status to in-progress and start the timer (vk begin <id>).
+2. Work each subtask; add notes/comments as you go.
+3. If blocked, set status blocked + explain why.
+4. When finished:
+   - Stop timer + set status done (vk done <id> "summary").
+   - Attach deliverables / link to repo.
+   - Fill the lessons learned field if anything should go into AGENTS/CLAUDE.
+5. If you touched code, queue cross-model review task before marking done.
+```
+
+Store this under `shared/prompt-registry/agent-task-workflow.md` so every agent run is consistent.
+
+---
+
+## Lessons Learned & Notifications
+
+- Always populate the **Completion Summary**. This becomes the notification that humans skim.
+- If the task produced a reusable insight, add it to the **Lessons Learned** field so it surfaces in the global lessons feed (future docs).
+- Notify humans via CLI: `vk comment <id> "@channel shipped" --author Veritas`
+
+---
+
+## Escalation
+
+| Situation               | Action                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| Blocked > 15 minutes    | Set status `blocked`, leave blocker comment, ping PM.                           |
+| Time tracking forgotten | Start timer immediately, add manual entry for elapsed time with reason.         |
+| Reviewer disagrees      | Re-open task, create subtasks for fixes, keep cross-model reviewer in the loop. |
+
+Follow this SOP and every task stays audit-friendly, searchable, and trustworthy.
--- a/docs/SOP-cross-model-code-review.md
+++ b/docs/SOP-cross-model-code-review.md
@ -0,0 +1,96 @@
+# SOP: Cross-Model Code Review (Claude ↔ GPT)
+
+**Rule (non-negotiable):** If Claude wrote it, GPT reviews it. If GPT wrote it, Claude reviews it. The author may self-check during development, but the final gate must be a different model.
+
+---
+
+## When to Trigger
+
+| Work Type                        | Review Required?                    |
+| -------------------------------- | ----------------------------------- |
+| Application code, infra, scripts | ✅ Always                           |
+| Docs/content                     | ⚠️ Only if accuracy/safety critical |
+| Research summaries               | Optional (human discretion)         |
+
+If in doubt, review.
+
+---
+
+## Workflow
+
+1. **Authoring task completes** (status remains `in-progress`).
+2. **Create review task** referencing the original:
+   - Title: `Review: <orig task title>`
+   - Type: `code`
+   - Sprint/project identical
+   - Description includes acceptance criteria + diff link(s)
+3. **Assign to opposite model** (via OpenClaw or other orchestrator):
+   ```
+   Hey Codex, review PR for task_1234. Checklist below.
+   ```
+4. **Reviewer steps**:
+   - Pull branch / run tests (if applicable)
+   - Use `docs/SOP-agent-task-workflow.md` for lifecycle
+   - Log findings as subtasks or checklist entries
+   - Severity tagging: High / Medium / Low / Nit
+5. **Outcomes**:
+   - ✅ No issues → comment summary + mark review task done → original task can go to `done`
+   - ❌ Issues → create fix subtasks on original task, set status `blocked` until resolved
+6. **Comms**: Reviewer leaves structured comment:
+   ```
+   ## Findings
+   - [High] Path traversal (see notes)
+   - [Low] Missing aria-label
+   ## Verdict
+   Changes required.
+   ```
+7. **Audit trail**: Update commit message or PR description with `[author: claude-sonnet-4-5][reviewed-by: gpt-5.1-codex]`.
+
+---
+
+## Review Checklist
+
+| Category          | Questions                                                        |
+| ----------------- | ---------------------------------------------------------------- |
+| **Security**      | Auth enforced? Input validated? Path traversal? Secrets handled? |
+| **Reliability**   | Error handling? Race conditions? Timeouts? File locking?         |
+| **Performance**   | Avoid O(n²)? Streaming vs buffering? Caching appropriate?        |
+| **Accessibility** | Keyboard support? aria-labels? Color contrast?                   |
+| **Docs**          | README/docs updated? Migration notes? Tests updated?             |
+
+Adapt per task type.
+
+---
+
+## Prompt Template (Reviewer)
+
+```
+You are the cross-model reviewer. The code was authored by <model>. Apply the checklist:
+1. Pull latest branch <branch>.
+2. Run tests (if any).
+3. For each issue, note severity (High/Medium/Low/Nit) + file/line + fix suggestion.
+4. Summarize verdict: Approve or Changes Required.
+5. Update task <id> with findings and completion summary.
+```
+
+Store in `shared/prompt-registry/cross-model-review.md`.
+
+---
+
+## Recording Findings
+
+- Add subtasks under the original task for each confirmed bug.
+- Reference GitHub issues if they existed.
+- Use Lessons Learned to capture systemic insights (e.g., “Always use withFileLock() when touching JSON stores”).
+
+---
+
+## Escalation
+
+| Scenario                                        | Action                                            |
+| ----------------------------------------------- | ------------------------------------------------- |
+| Reviewer disagrees with author but fix is minor | Leave comment + request change.                   |
+| Reviewer finds high severity bug                | Block task, ping human immediately.               |
+| Author disputes reviewer findings               | Create triage meeting or ask human to adjudicate. |
+
+This SOP preserved a 91% accuracy rate in RF-002. Keep following it.
--- a/docs/SOP-multi-agent-orchestration.md
+++ b/docs/SOP-multi-agent-orchestration.md
@ -0,0 +1,89 @@
+# SOP: Multi-Agent Orchestration (PM + Workers)
+
+When you ask “Hey Veritas, can you be the PM for this sprint and assign sub-agents?”, this is the playbook. One agent (usually Claude/Opus) acts as the project manager, spawns worker agents (Codex, Gemini, etc.), and reports back.
+
+---
+
+## Roles
+
+| Role             | Description                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| **PM Agent**     | Owns the sprint, breaks work into tasks/subtasks, assigns/monitors workers, posts progress. |
+| **Worker Agent** | Executes a single task end-to-end following the Agent Task SOP.                             |
+| **Human Lead**   | Creates the sprint, reviews PM outputs, handles escalations.                                |
+
+---
+
+## PM Agent Checklist
+
+1. **Read context**: AGENTS.md, sprint description, active tasks.
+2. **Plan**: If tasks missing, create them (see Sprint Planning SOP).
+3. **Assign**: For each task, either:
+   - Self-assign if it’s planning/reporting work.
+   - Spawn worker agent with clear instructions + acceptance criteria.
+4. **Track**:
+   - Update Agent Status panel using `vk agent sub-agent <count>`.
+   - Make sure each worker uses `vk begin/done` so timers stay accurate.
+5. **Review**:
+   - Run cross-model review before marking tasks done.
+   - Request fixes via subtasks or comments.
+6. **Report**:
+   - Post updates in task comments and daily standups (`vk summary standup --text`).
+   - Ping human lead when blockers persist > 30 minutes.
+
+---
+
+## Worker Handoff Template
+
+```
+Task: <ID> — <Title>
+Context: <link to research/requirements>
+Deliverable: <clear definition of done>
+Steps:
+1. Run vk begin <id>.
+2. Complete subtasks in order. Leave notes if deviations occur.
+3. If blocked, set status blocked + explain.
+4. On completion, vk done <id> "summary".
+5. Request cross-model review by creating task <new id> tagged review.
+Uploads: <where to store artifacts>
+```
+
+Store under `shared/prompt-registry/worker-handoff.md`.
+
+---
+
+## Status Reporting Expectations
+
+| Cadence                     | Mechanism                                            | Owner       |
+| --------------------------- | ---------------------------------------------------- | ----------- |
+| Start of day                | Comment on sprint tracker task summarizing plan.     | PM          |
+| After each worker completes | Worker comment + PM reaction (✅/request changes).   | Worker + PM |
+| Daily standup               | `vk summary standup --text` posted to comms channel. | PM          |
+| Sprint end                  | Archive tasks, write lessons learned, close sprint.  | PM          |
+
+Use emojis/reactions sparingly; detailed summaries live in comments.
+
+---
+
+## Error Escalation
+
+| Issue                      | PM action                                                  |
+| -------------------------- | ---------------------------------------------------------- |
+| Worker exceeds time budget | Stop timer, leave comment, ping human.                     |
+| Tooling failure (API down) | Run `pnpm dev:clean`, file issue, reassign.                |
+| Reviewer rejects work      | Re-open task, create fix subtasks, keep reviewer looped.   |
+| PM stuck                   | Escalate immediately — PMs should not be blocked > 15 min. |
+
+---
+
+## Example: Opus PM orchestrating Codex workers
+
+1. **Human**: `sessions_spawn` Opus with task “Be PM for US-1600”.
+2. **Opus (PM)**: Reads sprint tasks, assigns `US-1601` to itself (docs) and `US-1602` to Codex.
+3. **Opus**: Runs `vk agent sub-agent 1` to show a worker is active.
+4. **Opus**: Spawns Codex worker with handoff template; instructs to run `vk begin task_...` etc.
+5. **Codex**: Executes, posts completion summary, requests cross-model review from Claude.
+6. **Opus**: Reviews, marks done, updates sprint recap comment.
+7. **Opus**: Sets agent status back to idle once all workers complete (`vk agent idle`).
+
+Following this SOP keeps human oversight minimal while preserving accountability.
--- a/docs/SOP-sprint-planning.md
+++ b/docs/SOP-sprint-planning.md
@ -0,0 +1,134 @@
+# SOP: Sprint Planning with AI Agents
+
+Turn vague goals into a structured sprint the way we do internally: epics → sprint → tasks → subtasks. Agents can run most of this, but only if we give them a repeatable script.
+
+---
+
+## Hierarchy Refresher
+
+| Level                 | Description                                  | Example                        |
+| --------------------- | -------------------------------------------- | ------------------------------ |
+| **Epic / Initiative** | Multi-sprint outcome, named scope-of-record. | "MessageMeld Launch"           |
+| **Sprint**            | Time-boxed slice (`US-1600`, `BM-01`).       | "US-1600 — SOP Sprint"         |
+| **Task**              | Single deliverable tracked on the board.     | "US-1601: 5-Minute Quickstart" |
+| **Subtask**           | Checklist item inside a task.                | "Add screenshots"              |
+
+Use `project` to represent product buckets (veritas-kanban, brainmeld, digital-meld) and `sprint` for the current iteration name.
+
+---
+
+## Prompt Template (Sprint Planner Agent)
+
+```
+Goal: <describe epic>
+Project: <project name>
+Sprint name: US-XXXX — <tagline>
+Timebox: <dates or length>
+
+1. Break the goal into 4-8 tasks (type, priority, acceptance criteria).
+2. For each task add 3-8 subtasks that can be completed in under a day.
+3. Tag each task with the sprint and project.
+4. Assign task types (code, feature, research, docs, etc.).
+5. Output JSON payload ready for POST /api/tasks (array of tasks).
+6. After creation, post a summary comment to the sprint lead.
+```
+
+Store the final prompt under `shared/prompt-registry/sprint-planning.md`.
+
+---
+
+## API Creation Flow
+
+Use the bulk endpoint to create the entire sprint quickly:
+
+```bash
+curl -X POST http://localhost:3001/api/tasks/bulk \
+  -H "Authorization: Bearer <admin-key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tasks": [
+      {
+        "title": "US-1601: 5-Minute Quickstart",
+        "description": "Guide that takes users from zero ➝ agent-ready in 5 min",
+        "project": "veritas-kanban",
+        "sprint": "US-1600",
+        "type": "docs",
+        "priority": "high",
+        "subtasks": [
+          {"title": "Prereqs section"},
+          {"title": "Install steps"},
+          {"title": "Agent hookup"}
+        ]
+      }
+    ]
+  }'
+```
+
+CLI alternative:
+
+```bash
+vk create "US-1601: 5-Minute Quickstart" \
+  --project veritas-kanban \
+  --sprint US-1600 \
+  --type docs \
+  --priority high
+```
+
+Add subtasks via UI or `vk update --subtask "Add screenshots"` (coming soon).
+
+---
+
+## Estimation Pattern
+
+We track estimates implicitly via subtasks: each subtask ≈ half-day of effort. Keep tasks between **1–3 days** of work. If it needs more, split it before the sprint starts.
+
+1. Count subtasks (N).
+2. Multiply by 0.5 days to get a gut-check estimate.
+3. Compare against sprint capacity (agents × days × focus factor).
+
+Example: 6 tasks × 4 subtasks × 0.5d = 12 agent-days. With 3 agents @ 4 days focus → 12 days capacity → sprint is feasible.
+
+---
+
+## Assignment Workflow
+
+1. Tag each task with `owner` only if it is truly pre-assigned. Otherwise leave unassigned so agents can pull.
+2. Use **Projects** to separate product lines; use board filters when assigning.
+3. Start timers at task pickup (`vk begin`).
+4. Use the Agent Status sidebar to confirm at most 1 active task per agent.
+
+---
+
+## Example Sprint (excerpt)
+
+| Task                               | Type | Priority | Notes                     |
+| ---------------------------------- | ---- | -------- | ------------------------- |
+| US-1601: 5-Min Quickstart          | docs | high     | This guide.               |
+| US-1602: Task Workflow SOP         | docs | high     | Defines lifecycle.        |
+| US-1603: Sprint Planning SOP       | docs | medium   | This document.            |
+| US-1604: Multi-Agent Orchestration | docs | medium   | PM + workers.             |
+| US-1605: Cross-Model Review        | docs | medium   | Opposite model gate.      |
+| US-1606: Best Practices            | docs | medium   | Patterns + anti-patterns. |
+
+Clone this pattern for your own projects; rename sprint `US-YYYY` and fill tasks accordingly.
+
+### Example: Bug Fix Sprint (RF-002 cleanup)
+
+| Task                               | Type   | Priority | Notes                                     |
+| ---------------------------------- | ------ | -------- | ----------------------------------------- |
+| RF-002-A: Harden archive API       | bugfix | high     | Add withFileLock + validation.            |
+| RF-002-B: Fix sidebar counts       | bugfix | medium   | Sync TaskRepository + StatusHistory.      |
+| RF-002-C: Add regression tests     | qa     | medium   | Playwright coverage for archive + counts. |
+| RF-002-D: Update docs + postmortem | docs   | medium   | Summarize lessons in AGENTS.md + README.  |
+
+This mirrors how we handled the RF-002 audit sprint: tight scope, cross-functional subtasks, and clear notes for each fix.
+
+---
+
+## After Planning
+
+- Drop sprint recap in `docs/` or `memory/` so the team has context.
+- Create GitHub Milestone matching the sprint name (keeps issues + tasks aligned).
+- Schedule daily standup summary: `vk summary standup --date today`.
+
+Planning done right means agents always know what to pick up next.
--- a/docs/TIPS-AND-TRICKS.md
+++ b/docs/TIPS-AND-TRICKS.md
@ -0,0 +1,94 @@
+# Tips & Tricks — Power User Features
+
+Little things that keep Veritas Kanban fast when you live in it all day.
+
+---
+
+## CLI Shortcuts
+
+| Command                     | What it does                                                     |
+| --------------------------- | ---------------------------------------------------------------- |
+| `vk begin <id>`             | Sets status → in-progress, starts timer, agent status → working. |
+| `vk done <id> "summary"`    | Stops timer, sets done, posts summary, agent status → idle.      |
+| `vk block <id> "reason"`    | Blocks task + leaves blocker comment.                            |
+| `vk unblock <id>`           | Restarts timer and sets in-progress.                             |
+| `vk time`                   | Shows today’s breakdown (per task + total).                      |
+| `vk summary standup --text` | Generates markdown standup summary.                              |
+
+Pipe outputs to `jq` or `fzf` for custom dashboards.
+
+---
+
+## Keyboard Shortcuts (Web)
+
+| Shortcut           | Action                                          |
+| ------------------ | ----------------------------------------------- |
+| `Cmd/Ctrl + K`     | Command palette (jump to projects/tasks/views). |
+| Arrow keys + Enter | Navigate board cards → open detail panel.       |
+| `Esc`              | Close modals/panels quickly.                    |
+| `/`                | Focus global search (from palette).             |
+
+> Command palette replaces the old shortcuts dialog — type to filter actions, tasks, or navigation targets.
+
+---
+
+## Command Palette Power Moves
+
+- Type `create` to spawn new tasks anywhere.
+- Type `filter` to jump between saved filters (Today, Blocked, etc.).
+- Use `>` to execute actions (“>start timer task_123”).
+
+---
+
+## WebSocket Awareness
+
+- Connection status indicator (header) shows live state.
+- When offline, the app increases polling frequency; you can throttle it in Settings → Data.
+- Use `/api/health` + WebSocket inspector to debug proxies.
+
+---
+
+## MCP Server & Claude Desktop
+
+1. Build once: `cd mcp && pnpm build`
+2. Configure Claude Desktop `settings.json`:
+   ```json
+   {
+     "command": "node",
+     "args": ["/path/to/veritas-kanban/mcp/dist/index.js"],
+     "env": {
+       "VK_API_URL": "http://localhost:3001",
+       "VK_API_KEY": "<admin-key>"
+     }
+   }
+   ```
+3. Claude can now list tasks, create tasks, and update statuses via MCP.
+
+Combine MCP + prompt registry to let Claude act as your PM.
+
+---
+
+## Git Worktree Integration
+
+- Start a worktree from any task via the UI (“Create worktree”).
+- Branch naming follows `tasks/task_<id>` pattern — align commit messages with `[author: model]` tags.
+- Use `scripts/git-sync.sh` (if configured) to push to multiple remotes.
+
+---
+
+## Obsidian / Knowledge Vault Integration
+
+- Store deliverables under `Brain/dm-bg/...` (or your equivalent) using `scripts/brain-write.sh` to mirror workspace ↔ Brain.
+- Link from tasks: `See Brain/dm-bg/projects/...` for quick retrieval.
+- For bidirectional linking, mirror CLAUDE/AGENTS updates back into the vault after each sprint.
+
+---
+
+## Miscellaneous Quality-of-Life
+
+- **Dev cleanup:** `pnpm dev:clean` frees hung ports/watchers.
+- **Watchdog:** `pnpm dev:watchdog` auto-restarts when `/api/health` fails.
+- **Archive page:** Use the full-page Archive (accessible from board navigation) instead of the sidebar for faster search and filtering.
+- **Notifications:** Configure Teams/Slack/webhooks once; agents can trigger them via the API.
+
+Know a trick that belongs here? Add it and mirror to the knowledge base so agents learn it too.
--- a/scripts/dev-clean.sh
+++ b/scripts/dev-clean.sh
@ -10,6 +10,16 @@ set -euo pipefail

 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

+# launchd sessions often have a minimal PATH; resolve pnpm explicitly.
+PNPM_BIN="$(command -v pnpm || true)"
+if [[ -z "${PNPM_BIN}" && -x "/opt/homebrew/bin/pnpm" ]]; then
+  PNPM_BIN="/opt/homebrew/bin/pnpm"
+fi
+if [[ -z "${PNPM_BIN}" ]]; then
+  echo "[dev-clean] ERROR: pnpm not found in PATH and /opt/homebrew/bin/pnpm missing" >&2
+  exit 1
+fi
+
 SERVER_PORT="${PORT:-3001}"
 WEB_PORT="${WEB_PORT:-3000}"

@ -73,4 +83,4 @@ sleep 0.5

 echo "[dev-clean] starting pnpm dev"
 cd "${REPO_ROOT}"
-exec pnpm dev
+exec "${PNPM_BIN}" dev
--- a/scripts/dev-watchdog.sh
+++ b/scripts/dev-watchdog.sh
@ -12,9 +12,20 @@ PORT="${PORT:-3001}"
 INTERVAL_SECONDS="${WATCHDOG_INTERVAL_SECONDS:-30}"
 FAIL_THRESHOLD="${WATCHDOG_FAIL_THRESHOLD:-3}"

+# launchd sessions often have a minimal PATH; resolve pnpm explicitly.
+PNPM_BIN="$(command -v pnpm || true)"
+if [[ -z "${PNPM_BIN}" && -x "/opt/homebrew/bin/pnpm" ]]; then
+  PNPM_BIN="/opt/homebrew/bin/pnpm"
+fi
+if [[ -z "${PNPM_BIN}" ]]; then
+  echo "[dev-watchdog] ERROR: pnpm not found in PATH and /opt/homebrew/bin/pnpm missing" >&2
+  exit 1
+fi
+
 URL="http://localhost:${PORT}/api/health"

 fails=0
+LOCK_FILE="${WATCHDOG_LOCK_FILE:-/tmp/veritas-kanban-dev-clean.lock}"

 echo "[dev-watchdog] repo=${REPO_ROOT}"
 echo "[dev-watchdog] url=${URL} interval=${INTERVAL_SECONDS}s threshold=${FAIL_THRESHOLD}"
@ -30,9 +41,23 @@ while true; do
  fi

  if [[ "${fails}" -ge "${FAIL_THRESHOLD}" ]]; then
-    echo "[dev-watchdog] unhealthy threshold reached -> restarting via pnpm dev:clean"
+    echo "[dev-watchdog] unhealthy threshold reached -> restarting via scripts/dev-clean.sh"
+    # Prevent restart storms (e.g., if health endpoint is down for an extended period)
+    if [[ -f "${LOCK_FILE}" ]]; then
+      lock_pid="$(cat "${LOCK_FILE}" 2>/dev/null || true)"
+      if [[ -n "${lock_pid}" ]] && kill -0 "${lock_pid}" 2>/dev/null; then
+        echo "[dev-watchdog] restart already in progress (pid=${lock_pid}); waiting"
+        fails=0
+        sleep "${INTERVAL_SECONDS}"
+        continue
+      fi
+    fi
+
    cd "${REPO_ROOT}"
-    exec pnpm dev:clean
+    # Run dev-clean in background so the watchdog can keep monitoring.
+    (bash "${REPO_ROOT}/scripts/dev-clean.sh") &
+    echo $! > "${LOCK_FILE}"
+    fails=0
  fi

  sleep "${INTERVAL_SECONDS}"
--- a/web/src/components/board/BulkActionsBar.tsx
+++ b/web/src/components/board/BulkActionsBar.tsx
@ -2,6 +2,7 @@ import { useState, useMemo } from 'react';
 import { X, Trash2, Archive, ArrowRight, Inbox } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Select, SelectContent, SelectItem, SelectTrigger } from '@/components/ui/select';
+import { useToast } from '@/hooks/useToast';
 import {
  AlertDialog,
  AlertDialogAction,
@ -52,6 +53,7 @@ interface BulkActionsBarProps {
 export function BulkActionsBar({ tasks }: BulkActionsBarProps) {
  const { selectedIds, isSelecting, toggleSelecting, selectAll, toggleGroup, clearSelection } =
    useBulkActions();
+  const { toast } = useToast();

  const updateTask = useUpdateTask();
  const deleteTask = useDeleteTask();
@ -123,8 +125,43 @@ export function BulkActionsBar({ tasks }: BulkActionsBarProps) {

  const handleArchiveSelected = async () => {
    setIsProcessing(true);
+    const taskIds = Array.from(selectedIds);
+    let successful = 0;
+    let failed = 0;
+
    try {
-      await Promise.all(Array.from(selectedIds).map((id) => archiveTask.mutateAsync(id)));
+      // Archive each task individually to track success/failure
+      for (const id of taskIds) {
+        try {
+          await archiveTask.mutateAsync(id);
+          successful++;
+        } catch (error) {
+          failed++;
+          console.error(`Failed to archive task ${id}:`, error);
+        }
+      }
+
+      // Show appropriate feedback
+      if (failed > 0 && successful > 0) {
+        toast({
+          variant: 'default',
+          title: 'Partial Archive',
+          description: `Archived ${successful} of ${taskIds.length} tasks. ${failed} failed.`,
+        });
+      } else if (failed > 0) {
+        toast({
+          variant: 'destructive',
+          title: 'Archive Failed',
+          description: `Failed to archive all ${taskIds.length} selected tasks.`,
+        });
+      } else if (successful > 0) {
+        toast({
+          variant: 'default',
+          title: 'Success',
+          description: `Archived ${successful} task${successful !== 1 ? 's' : ''}.`,
+        });
+      }
+
      clearSelection();
    } finally {
      setIsProcessing(false);
--- a/web/src/hooks/useTasks.ts
+++ b/web/src/hooks/useTasks.ts
@ -114,13 +114,21 @@ export function useUpdateTask() {

      const cachedTask = queryClient.getQueryData<Task>(['tasks', serverTask.id]);
      queryClient.setQueryData(['tasks', serverTask.id], mergeWithCachedTimeTracking(cachedTask));
+
+      // GH-87: Invalidate metrics cache if status changed to keep sidebar in sync.
+      // The sidebar relies on useMetrics() which has a 30s refetch interval + 10s staleTime.
+      // Without this, sidebar counts can lag behind the actual board state.
+      if (input.status) {
+        queryClient.invalidateQueries({ queryKey: ['metrics'] });
+      }
    },
-    // NOTE: No onSettled invalidation here. The onSuccess handler already
+    // NOTE: No general onSettled invalidation here. The onSuccess handler already
    // patches the cache with the server response (preserving timer state).
    // An aggressive invalidateQueries would trigger a background refetch
    // whose response could overwrite timer state that was patched between
    // the mutation start and the refetch completing. The WebSocket
    // task:changed events and polling handle eventual consistency.
+    // Status-specific metrics invalidation is handled above (GH-87).
  });
 }