veritas-kanban

# CLAUDE.md — Claude-Specific Supplement for Veritas Kanban

> **Canonical instructions are in `AGENTS.md`.** Read that file first. This supplement contains
> Claude-specific lessons and common mistakes caught by previous Claude runs. Do not duplicate
> `AGENTS.md` content here.
>
> **Last updated:** 2026-08-30 (v6.1.3 release freshness)
> **Freshness check:** Update after mistakes; review monthly.

---

## What changed in v2.1

`AGENTS.md` is now the canonical project instruction file. It supersedes the duplicate context
that was previously embedded here. The fields updated from their stale v2.0 values:

- **pnpm:** was `9+` → now `≥ 11.0.0` (pinned `pnpm@11.1.1`)
- **Node:** was `22+` → now `≥ 22.22.1`
- **Providers:** managed Buzz, Grok Build, Codex, Claude Code, Copilot CLI,
  Hermes, and OpenClaw contracts are documented in `AGENTS.md`

---

## Lessons learned (Claude-specific)

### Security

- ❌ Forgot global middleware — flagged missing per-route auth that was already in `app.use()`.
  Global middleware is in `server/src/middleware/`; check there before adding per-route auth.
- ❌ Used `path.join()` without validation — allows `../` traversal.
  Always follow with `validatePathSegment()` + `ensureWithinBase()`.

### Architecture

- ❌ Imported `fs` directly in service files — breaks storage abstraction.
- ❌ Added polling when WebSocket hook existed — use `useRealtimeAgentStatus`.
- ❌ Frontend interface didn't match server response (`totalAgents` vs `total`).
  Server response is the source of truth; interfaces must match exactly.
- ❌ Agent provider guessing — always verify flag names and interfaces against versioned docs
  before implementing a new provider adapter.

### Testing

- ❌ Used wrong schema field in test fixtures (`status: "success"` vs `success: true`).
  Copy fixture shapes from live runtime output or type definitions, not from memory.
- ✅ `pnpm-lock.yaml` is generated by pnpm; never reformat or hand-edit it.

### Multi-agent runtime

- Heartbeat timeout: 5 min. Stale-check interval: 1 min.
- Activity source of truth: `status-history` files, not `activity.json`.
- Dashboard optimistic updates: use `onMutate`, not refetch-after-mutate.

---

## When to update this file

- After a mistake that a rule would have prevented.
- After any review catches a systemic pattern worth preserving.
- Monthly freshness review.

---

_Structure inspired by Anthropic's CLAUDE.md convention._