veritas-kanban: Instructions file for Codex

AGENTS.md — Canonical Agent Instructions for Veritas Kanban

Canonical source. Contributors and harnesses with repository-instruction discovery read this file first. Every Veritas-managed run also receives an immutable task envelope; do not assume a provider that disables custom instructions reads repository files implicitly. Harness-specific supplements (for example CLAUDE.md) extend, never duplicate or contradict, these rules. See docs/AGENTS-TEMPLATE.md for the managed-run and external-agent protocols.

Version: 6.3.0 Freshness policy: update within two working days of any toolchain or architecture change. Stale fields (package manager, Node version, provider list, test commands) are caught by pnpm check:pnpm-settings and local release checks.

---

Runtime requirements

Tool	Required version	How to verify
Node.js	≥ 22.22.1	node --version
pnpm	≥ 11.0.0	pnpm --version
Git	≥ 2.38	git --version

The packageManager field in package.json is pinned to [email protected]. Do not install with npm or yarn. Do not up-rev the pin without updating this file.

---

Repository layout

veritas-kanban/
├── server/          Express + TypeScript API, agent orchestration, storage
├── web/             React + Vite SPA
├── cli/             Commander.js CLI (mirrors API endpoints)
├── shared/          Shared TypeScript types and utilities
├── mcp/             MCP server
├── desktop/         Electron desktop wrapper
├── docs/            Operator and developer documentation
├── prompt-registry/ Prompt templates
└── .veritas-kanban/ Runtime data: agent-registry, logs, telemetry

Workspaces are declared in pnpm-workspace.yaml.

---

Essential commands

# Install
pnpm install

# Build (all workspaces in dependency order)
pnpm build

# Dev server (server + web, hot-reload)
pnpm dev

# Tests
pnpm test                       # Canonical sequential workspace unit gate
pnpm test:unit                  # Shared build, then server, web, CLI, and MCP
pnpm test:coverage              # Critical-path V8 coverage, HTML/JSON reports, and ratchets
pnpm test:e2e                   # Playwright end-to-end, zero retries

# Type check (builds shared first)
pnpm typecheck

# Lint / fix
pnpm lint
pnpm lint:fix

# Smoke checks
pnpm check:actions-pinned       # Rejects mutable external GitHub Action references
pnpm check:pnpm-settings        # Validates package manager fields match this file
pnpm check:tracked-ignore       # Rejects tracked files covered by ignore rules
pnpm check:coverage-policy      # Validates coverage policy, configs, CI, and regression tests
pnpm check:delivery-cadence     # Prevents verification and review policy drift
pnpm check:security-gates       # Validates CodeQL/gitleaks workflow and exact suppressions
pnpm check:gitleaks             # Scans reviewed tree and proves new-secret detection
pnpm check:vite-native-config   # Loads web build and test configs with Vite's native loader
pnpm check:service-filesystem-boundary # Prevents new direct filesystem imports in services
pnpm test:ci-scope              # Validates path-aware CI test selection
pnpm smoke:cli-mcp              # CLI ↔ MCP compatibility smoke test
pnpm test:buzz:compatibility    # Credential-free composed Buzz release gate