mirror of
https://github.com/BradGroux/veritas-kanban.git
synced 2026-08-28 02:44:59 +00:00
dfae7911cc
* chore: prepare v6.1.2 release * chore: refresh reviewed gitleaks fingerprints * docs: record release gate corrections * docs: record v6.1.2 release evidence
64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# 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-24 (v6.1.2 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._
|