veritas-kanban/AGENTS.md

# 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.1.4
> **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 the smoke-test CI job.

---

## 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 `pnpm@11.1.1`. 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 and optional review workflows
└── .veritas-kanban/ Runtime data: agent-registry, logs, telemetry
```

Workspaces are declared in `pnpm-workspace.yaml`.

---

## Essential commands

```bash
# 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
```

Do not run `npm install`, `yarn`, or `bun install`. If lockfile conflicts arise, resolve with
`pnpm install` and commit the updated `pnpm-lock.yaml` without reformatting it.

---

## GitHub workflow

- Use the authenticated GitHub CLI (`gh`) as the default interface for GitHub issues, pull
  requests, releases, workflow runs, and API calls.
- Use `git` for local repository operations and `gh` for GitHub-hosted state.
- Do not loop through alternate connectors or permission paths while `gh` is authenticated and
  can perform the operation.
- Fall back only when `gh` is unavailable or cannot support the required operation. Report the
  exact blocker before changing paths.
- Source every published GitHub release body from `docs/releases/vX.Y.Z.md` and pass that file
  to `gh release create` or `gh release edit` with `--notes-file`.
- Never hand-author or repair a release body with `--notes`, the GitHub editor, or a raw API
  body. Edit the reviewed source file first, validate it, and publish that exact file.
- Keep each prose paragraph and list item on one logical Markdown source line. Separate blocks
  with blank lines. Do not hard-wrap release prose or add carriage returns, trailing-space hard
  breaks, literal escaped newlines, HTML `<br>` tags, or blockquotes.
- Prefer compact, natural paragraphs over bullet-per-sentence formatting. Use lists only for
  genuinely parallel items. Keep rendered prose blocks concise so they do not become walls of
  text on GitHub's release index.
- Run `pnpm validate:release -- --version X.Y.Z --native-evidence /absolute/path/evidence.json --native-app /absolute/path/veritas-kanban.app --media-evidence /absolute/path/capture/publication.json` against the clean publication checkout. The publication manifest must bind the untouched capture from the exact packaged build; only the documented regular documentation/media paths may change afterward. Source or dependency changes require a fresh build and capture. The post-publication `--github` form also requires the published GitHub body and tag to match the reviewed publication commit. `--source-only` is a separate source preflight, not release acceptance; `--skip-build-output` does not bypass native or documentation-media evidence.
- After publication, inspect both the releases index and tag page. Raw Markdown validation does
  not replace a rendered-format check.

---

## Sustainable execution cadence

- Keep each issue and pull request to one independently shippable behavior. When implementation
  reveals a separable UI surface, secondary integration, refactor, or hardening follow-up, open
  a linked issue instead of expanding the active pull request.
- Re-scope before continuing when an issue no longer fits one coherent review, an unexpected
  subsystem becomes necessary, or verification work is larger than the behavior being changed.
- At the 45-minute delivery checkpoint, if the issue is not pull-request ready, stop adding scope
  and report the concrete cause. Split independent remaining work into linked issues, or continue
  only when the next step is required to preserve correctness of the current behavior.
- During ordinary implementation, use source inspection, changed-file formatting/linting, and
  touched-package type checking. Do not run workspace unit, coverage, E2E, desktop packaging, or
  Docker contract tests between implementation PRs.
- When a maintainer explicitly declares a focused diagnostic milestone, run the exact Vitest slice
  once with
  `pnpm --filter <package> exec vitest run <exact-test-files>`. Do not use
  `pnpm --filter <package> test -- <test-files>` or
  `pnpm --filter <package> test -- --run <test-files>`; package wrappers can ignore that file
  boundary and expand into the entire package suite.
- Do not rerun an unchanged passing gate after documentation, comments, or formatting-only edits.
  Rerun only the checks affected by the later change.
- Use the complete workspace suite once at an explicit integration, critical-security, or release
  milestone. Pull-request label `ci:full`, scheduled CI, and manual full dispatch are the
  authoritative broad gates. Critical coverage, unsigned desktop artifacts, and the Docker image
  contract run only at those milestones.
- Trust `scripts/select-ci-test-scope.mjs` and the `Select Test Scope` job to record the required
  CI tier. Ordinary pull requests and `main` pushes select no workspace tests. Do not add local
  test gates merely to duplicate a future milestone.
- Do not wait for optional desktop packaging, artifact previews, or release workflows when the
  change does not touch their product boundary. They are evidence only when declared relevant.
- Add enough regression coverage to prove the behavior and its meaningful failure modes. Test
  count is not a quality target.

---

## Architecture rules

### Server (Express + TypeScript)

- All routes go through centralized middleware in `server/src/middleware/`.
- Auth: JWT + API keys. Dev bypass: `VERITAS_AUTH_LOCALHOST_BYPASS=true`.
- Storage: always go through `storage/interfaces.ts`. Never import `fs` directly in service files.
- Append-only durable records must complete the entire serialized write before
  sync. Never assume one `FileHandle.write()` call wrote every byte or ignore
  `bytesWritten`.
- Error classes: `UnauthorizedError`, `ForbiddenError`, `BadRequestError`, `InternalError`.
- Pagination: `sendPaginated(res, items, { page, limit, total })`.
- Path traversal: always call `validatePathSegment()` on any user-supplied path component,
  then `ensureWithinBase(base, resolved)` before file I/O.
- SQLite journal conversion runs from the bootstrap before `server.ts` imports routes. Normal
  startup eagerly creates many independent SQLite handles, so a live API handler cannot prove
  exclusive database ownership.
- Governed SQLite `DELETE` or expert-override mode requires the signed external policy and the
  reference-counted process/host ownership lock. Do not reuse the short-lived generic `FileLock`
  for authoritative database ownership.

### Web (React + Vite)

- State: Zustand stores. No prop drilling past 2 levels.
- Realtime: `useRealtimeUpdates` WebSocket hooks. Do not add polling when a hook exists.
- Styling: Tailwind CSS with component-scoped overrides.
- Frontend interfaces must exactly match server response shapes. Server is the source of truth.

### CLI (Commander.js)

- Every command mirrors an API endpoint.
- `--json` flag for machine-readable output.
- Colored output via `chalk`.

### Shared types

- All cross-package types live in `shared/src/types/`.
- `AgentProvider` union is the single definition consumed by both server and web.
  **Currently supported providers:**
  `openclaw` | `codex-cli` | `codex-sdk` | `codex-app-server` | `codex-cloud` |
  `claude-code` | `acp-stdio` | `hermes-cli` | `ollama-local` | `ollama-cloud` |
  `lm-studio-local` | `custom`
- Executable task adapters are currently `openclaw`, `codex-cli`, `codex-sdk`,
  `codex-app-server`, `claude-code`, `acp-stdio`, and `hermes-cli`. Explicitly
  configured providers outside that set must fail closed; never route them
  through an implicit OpenClaw fallback.
- Probe and persist `provider-runtime-manifest/v1` before mutating attempt state.
  New runtime controls must use the persisted evidence instead of provider-name
  checks, and provider version/build changes must invalidate cached conformance.
  Increment `PROVIDER_RUNTIME_PROBE_REVISION` whenever probe semantics or the
  built-in adapter capability evidence changes.
- Normalize every configured harness through `harness-support-profile/v1`.
  Settings, API diagnostics, `vk doctor`, dispatch, and telemetry must use the
  same support tier and redacted readiness evidence. Only known legacy records
  whose built-in type and command both identify `codex` or `hermes` may infer a
  provider during migration; provider-less or profile/adapter-mismatched records
  fail closed before an attempt is created.
- Route direct, profile, conversation, provider-handoff, child-agent, retry,
  fallback, scheduled, watcher, and workflow launches through the shared
  admission controller. A `queued` response means Veritas durably accepted
  ownership; harnesses must not submit a duplicate or create a hidden
  provider-side queue. Provider adapters require
  `provider-admission-evidence/v1` before dispatch.
- Phase authority uses the versioned contracts in
  `shared/src/types/phase-capability.types.ts`. Compile parent, phase, agent
  profile, sandbox, tool-catalog, and launch-policy authority only through
  `phase-capability-service.ts`; never union scopes or infer missing
  dimensions. The plan artifact exception is one harness-owned exact path and
  never implies general filesystem write authority. Active phase changes go
  only through `phase-transition-service.ts` with exact attempt, sequence,
  evidence-digest, and launch-manifest compare-and-set guards. Authority
  expansion requires an exact-action approval; an emergency override requires
  `admin:manage`, expires within 24 hours, and is durably reverted. Every task
  launch, workflow step, retry or fallback, resume, follow-up, fork, compaction
  control, and provider handoff must bind the effective phase before attempt
  mutation. Descendants inherit and intersect the exact parent launch or
  transition evidence and cannot widen it. Explicit phases fail closed when any
  required dimension is not enforceable. Run tool catalogs are filtered by the
  launch phase, mediated calls re-check the active phase, and approvals bind the
  exact phase evidence and transition sequence. ACP stdio is the only current
  adapter with enforceable command and external-action mediation; other
  adapters return typed blockers for explicit phases.
- Operator Run Access changes compile server-owned built-in phase targets
  against the immutable launch authority ceiling. Preview and apply bind the
  exact attempt, manifest, Run Access digest, phase digest, sequence, stable
  request ID, requested operation, reason, and request revision. Added scopes
  require exact-action approval. ACP stdio
  may apply only live mediated command, external-action, and plan-artifact
  changes; process-boundary changes require pause and relaunch, and unsupported
  adapters fail closed without appending a transition.
- Credential-bound tool servers persist only exact definition/scope digests and
  safe target names in `run-tool-catalog/v1`. Discovery strips their source
  environment/header values, native provider injection omits them, and
  mediated invocation issues exact-action leases using the server-owned launch
  manifest digest. Credential-bound sessions are one-shot and raw values may
  exist only inside the controlled downstream dispatch callback.
- Providers access credential-bound tools only through the system-owned
  `veritas-run` MCP bridge and an opaque in-memory run handle. Codex CLI/SDK,
  Codex app-server, Claude Code, and ACP stdio inject this shared contract;
  Hermes and OpenClaw fail closed until their certified transports can enforce
  it.
- Classify launch credentials through `run-launch-credential-plan/v1`.
  Provider boot authentication, task integration definition IDs, and explicit
  high-risk environment passthrough are separate classes. Task integration
  credentials fail closed until an accepted tool or egress boundary proves
  brokered, non-bypassable delivery.
- Atomically persist `admission-reservation/v1` before direct task attempts,
  workflow roots, executable workflow steps, pending-run state, or provider
  state. Workflow roots use the explicit `workflow-control` admission provider;
  provider-backed steps bind the resolved provider, selected host, root
  reservation, run, and step before attempt mutation. Capacity claims use the
  storage repository transaction or file lock, never process-local counters.
  Keep the invariant one-active-run-per-task policy and configured global,
  workspace, root-task, provider, and host ceilings aligned across dispatch,
  REST, and `vk`.
  Persist only a stable digest of caller-supplied idempotency values.
  Completion, interruption, cancellation, and start failure release once;
  restart recovery may reclaim only after the durable run supervisor verifies
  the original live process or session.
- Activate recurring work only through `automation-activation-preview/v1` and
  an exact critical human approval. Persist one immutable
  `automation-version/v1`, a compare-and-set scheduler binding, and a stable
  due-window claim before workflow admission. The saved standing scope is a
  ceiling: current workflow, phase, provider, tool, integration, credential,
  and budget policy may narrow or block each run and may never be widened by
  the automation version.
- Bind every executable reservation to `execution-tree-identity/v1`. Descendants
  retain the root objective and exact parent edge across resume, follow-up,
  fork, retry, fallback, provider handoff, workflow step, and child-agent
  launches. Claim capacity and aggregate budget in the same repository lock or
  transaction. Usage events must be idempotent and attributable to one node;
  never copy cumulative parent or descendant totals into another contributor.
  Release unused reservation while retaining committed usage.
- Persist `run-supervisor/v1` before provider dispatch. Restart recovery must
  validate the exact runtime, task-envelope, launch-manifest, worktree, host,
  lease, and process/session identity; replay only after the durable event
  cursor; and record a typed recovery action instead of starting duplicate work
  or signaling an unverified process.
- Resolve selected MCP servers through `tool-server-definition/v1` and persist
  an immutable `run-tool-catalog/v1` before provider dispatch. Required
  discovery failures block launch; optional failures remain visible and
  audited.
- Native provider configuration may expose only tools with an `allow`
  decision. Approval-required tools must use the Veritas-mediated
  `call_run_tool` path so the exact action hash is approved before dispatch.
- Tool-server environment values and credential values are never persisted.
  Credential-bound tool definitions remain fail-closed until the provider
  launch credential broker is active.
- Run-owned commands use `run-terminal-handle/v1`, never a provider's generic
  stdin channel. The current runtime supports background pipe mode with
  exact-action approval, stable request IDs, manifest-approved executable,
  cwd, and environment posture, bounded
  cursor-addressable redacted output, bounded single/any/all waits,
  foreground detachment, process-group termination, and durable journal
  reconstruction. A dangling handle becomes `interrupted` after restart
  because inherited pipes cannot be reattached safely. PTY, interactive stdin,
  and restart reattachment fail closed until their typed controls ship.
- Explicit run-terminal executable, script, loader, config, archive, and
  load-path inputs use `run-file-execution-approval-evidence/v1`. Bind exact
  provenance or launch-baseline digests into the approval, require a critical
  human-only decision for external or unknown bytes, and rehash immediately
  before spawn. Unsupported indirect and tool transports fail closed.
- File-backed Work Products use the exact manifest-bound `run-artifact` root
  exposed as `VERITAS_ARTIFACT_ROOT`. Register only completed relative files
  through the governed artifact service; never persist or expose the host root.
  Stored versions are immutable, downloads revalidate size and SHA-256, and
  quarantined bodies remain unavailable. See
  `docs/architecture/FILE-WORK-PRODUCTS-V1.md`.
- Harnesses start a run-owned command with
  `POST /api/v1/run-terminals/runs/:taskId/:attemptId/execute`. Send one stable
  `requestId`, a command plus argument array, `mode: "pipe"`, start mode,
  optional worktree-relative cwd, and environment names only. A `202`
  response requires an operator decision through `run-approvals`; retry the
  identical request after approval to receive the `201` handle. Never place
  credential values in arguments or environment fields.

---

## Agent provider notes

### OpenClaw (native tasks: v2026.9.2 or later)

- Task dispatch uses the gateway `/tools/invoke` endpoint with `sessions_spawn`.
- Native completion is server-owned: probe authenticated `agent.wait` before launch, persist the run ID
  and immutable attempt bindings, and capture only the gateway terminal reply. Never give a child
  a Veritas callback credential or infer completion from session history.
- Restart recovery resumes observation of the exact run; changed or missing identity requires recovery.
- **Required gateway policy:** `sessions_spawn` and `sessions_send` must be explicitly allowed
  on the operator-level gateway; they are blocked by default on fresh OpenClaw installs.
- Set `OPENCLAW_GATEWAY_URL` (default `http://127.0.0.1:18789`) and
  `OPENCLAW_GATEWAY_TOKEN` (required for native task completion).
- A pre-flight check is run before a task is marked active; policy denial returns an actionable
  configuration error.
- See `docs/AGENT-PROVIDERS.md` § OpenClaw for full setup instructions.

### Hermes Agent (v2026.7.7.2)

- Dispatch uses the one-shot scripted interface: `hermes -z <prompt>`.
- Hermes is spawned in the task worktree without a shell; stdout captures the final response,
  stderr captures diagnostics.
- Project instructions are loaded automatically from `AGENTS.md` in the worktree root.
- Session resume is not yet implemented; `--resume`/`--continue` are reserved for a future
  provider iteration.
- Provider ID: `hermes-cli`. Auth probe: `hermes --version`.
- Set `HERMES_API_KEY` or the appropriate model-provider key in the operator environment.
- See `docs/AGENT-PROVIDERS.md` § Hermes for full setup instructions.

### Codex (OpenAI)

- `codex-cli`: `codex exec --sandbox workspace-write --json`
- `codex-sdk`: programmatic SDK, requires `@openai/codex-sdk`
- `codex-app-server`: pinned to `codex-cli 0.145.0`; supervised JSON-RPC v2 over
  strict stdio for one task-bound thread and turn.
- App-server launch arguments are system-owned. Inherited MCP servers, hooks,
  plugins, apps, browser/computer tools, and remote control remain disabled.
  Selected run-scoped MCP servers are injected only through the immutable
  catalog's thread configuration.
- App-server consumes only the checked-in v0.145.0 schemas and exposes
  `initialize`, thread start/resume/fork/compact/archive, and turn
  start/steer/interrupt. `thread/shellCommand` is never reachable.
- `conversation-lifecycle/v1` persists opaque thread, turn, item, parent, and
  fork identities. Resume and fork validate the source launch manifest,
  provider/model/policy, base revision, and worktree compatibility before a new
  attempt is created.
- App-server command, file, permission, tool-question, and elicitation requests
  use `run-approval/v1`. Decisions must preserve the persisted revision and
  exact action hash; interruption and cancellation invalidate pending requests.
- Auth: `codex login status` / `OPENAI_API_KEY`

### Claude Code (v2.1.218)

- Provider ID: `claude-code`. Default command: `claude`.
- Veritas launches `claude --bare --print --output-format stream-json` with
  static sandbox-derived permissions and no shell.
- Bare mode requires explicit environment authentication. OAuth/keychain state
  reported by `claude auth status` does not prove bare-mode readiness.
- The terminal `result` record is authoritative. Veritas drains stdout after
  process close, persists `session_id`, and maps partial, hook, tool, subagent,
  usage, cost, and result records into `run-event/v1`.
- Resume uses the exact persisted session through system-owned `--resume`.
  Native history fork adds `--fork-session`; caller-supplied lifecycle flags
  remain prohibited. Run-scoped MCP uses a system-owned strict config and
  exposes only catalog tools with an `allow` decision.
- The shared approval broker is available, but Claude stays on static
  `dontAsk` permissions until its adapter exposes a pinned interactive
  request/response contract.

### Agent Client Protocol (ACP v1)

- Provider ID: `acp-stdio`. Configure the exact ACP agent command and arguments.
- Veritas launches the agent without a shell in the task worktree and negotiates
  stable ACP protocol version 1 before attempt mutation.
- Capability evidence comes from `initialize`; resume/load, fork, and close fail
  closed when the runtime does not advertise them.
- `session/update` records enter the causal run journal.
  `session/request_permission` uses the durable approval broker.
- Only immutable all-allow MCP server catalogs can be passed natively because
  ACP v1 has no per-tool allowlist. Profiles may explicitly require the
  system-owned `veritas-run` bridge for mediated catalogs; otherwise partial
  native catalogs fail closed.
- The built-in `buzz-agent` profile remains provider `acp-stdio`, pins Buzz
  `v0.4.24` at commit `710ed9fff57878a1d69f809b80a6ee0416c53fc4`, and rejects
  `buzz-acp`, version drift, session loading, and network MCP claims. Selected
  run tools are delivered only through the opaque, attempt-bound
  `veritas-run` bridge.
- The built-in `copilot` profile remains provider `acp-stdio`, pins Copilot CLI
  `v1.0.74`, owns the stdio safety argv, rejects broad allow/remote/TCP/config
  injection, and records public-preview plus incomplete-source limitations.
- The built-in `grok-build` profile remains provider `acp-stdio`, pins Grok
  Build `v0.2.111` build `94172f2aa4e5`, launches `grok agent --no-leader
stdio`, and rejects approval bypass, reauthentication, leader, plugin,
  endpoint, prompt, and resume argument injection.
- Harness certification uses `harness-conformance-suite/v1`; run the committed
  mock lane with `pnpm --filter @veritas-kanban/server exec tsx
src/scripts/run-harness-conformance.ts -- --suite <suite.json>
--observations <observations.json>`. Credential-gated lanes require explicit
  opt-in and never commit raw provider output or secrets.
- Cross-harness compatibility is published as
  `harness-compatibility-matrix/v1`. API, `vk doctor`, Settings, telemetry, and
  `docs/HARNESS-COMPATIBILITY.md` must use the reviewed profile capability
  digest, fixture revision, invalidation policy, and source caveats rather than
  defining provider-specific tiers.
- Runtime extensions use the in-process `runtime-hook/v1` bus. Only documented
  pre-events may deny, post-events remain passive, and arbitrary executable or
  HTTP handlers stay unsupported until their filesystem and egress boundaries
  are enforceable. See `docs/architecture/RUNTIME-HOOK-V1.md`.
- `vk acp serve --stdio` exposes one Veritas-managed task as an ACP v1 server
  view for editors and other ACP clients. Bind with `--task` or require
  `_meta["veritas/taskId"]` on `session/new`; client-owned MCP catalogs fail
  closed.
- ACP client disconnect never stops the durable Veritas run. Reconnect with
  `session/load` and `_meta["veritas/afterSequence"]`; cancellation uses the
  conversation interrupt path, not task termination.
- See `docs/AGENT-PROVIDERS.md` § ACP stdio agent provider.

---

## Security boundaries

- **No secrets in code.** Use environment variables or brokered credentials.
- **Input validation.** All user input is validated with Zod schemas before processing.
- **Path traversal.** `validatePathSegment()` + `ensureWithinBase()` on every user-supplied path.
- **Env passthrough.** Agents receive only the keys in the configured safe allowlist; see
  `server/src/utils/codex-env.ts`, `server/src/utils/hermes-env.ts`, and
  `server/src/services/claude-code-adapter.ts` plus
  `server/src/services/acp-stdio-adapter.ts`.
- **Launch arguments.** Never put credential values in provider commands or arguments; use an
  allowlisted environment key or run-scoped brokered credential reference.
- **Workspace execution trust.** Scan repository-controlled instructions,
  hooks, MCP servers, workflows, extensions, and provider configuration before
  launch. Bind the exact inventory and decision to the run launch manifest,
  then rescan before provider creation. Project policy may narrow trust only.
- **Log redaction.** Trace logs and telemetry run through `TRACE_SECRET_PATTERNS` before storage.
- **No credentials in PR descriptions, test fixtures, or log snippets.**
- **Artifact previews.** Passive file previews use `work-product-artifact-preview/v1`, authenticated artifact reads, validated content types, format-specific resource limits, and fail-closed statuses. Never render HTML in this boundary or expose host paths and storage keys.

---

## Testing expectations

- Framework: **Vitest** (server, cli, mcp), **React Testing Library** (web).
- Test files: `*.test.ts` co-located in `src/__tests__/` or alongside source.
- Aim for >80% coverage on critical paths (agent dispatch, auth, storage adapters).
- Use `vi.mock()`/`vi.fn()` to isolate external processes and HTTP calls; no live credentials
  in unit tests.
- Credential-gated smoke tests document the tested provider version in a `@smoke` describe block.
- Live MCP-to-HTTP integration groups require a running API and explicit
  `VK_MCP_INTEGRATION_TEST=1`; the default MCP test suite must remain
  server-independent.
- Match actual runtime schema in test fixtures — wrong field names (`status: "success"` vs
  `success: true`) are a common source of false-passing tests.

---

## Multi-agent runtime

- Agent registry: `.veritas-kanban/agent-registry.json` (file-based).
- Agent names: use ALL CAPS for acronyms (VERITAS, TARS, CASE, K-2SO, R2-D2, MAX).
- Heartbeat timeout: 5 min (configurable). Stale-check interval: 1 min.
- Activity data source of truth: `status-history` files, not `activity.json`.
- Dashboard optimistic updates: use `onMutate` in Zustand mutations.

---

## Conventions

| Artifact    | Style                                                     |
| ----------- | --------------------------------------------------------- |
| TS files    | `kebab-case.ts`                                           |
| Components  | `PascalCase.tsx`                                          |
| Variables   | `camelCase`                                               |
| Constants   | `UPPER_SNAKE_CASE`                                        |
| Git commits | Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`) |
| Branches    | `feat/description-issue-number`, `fix/...`, or `docs/...` |

---

## Code quality gates

1. **No direct `fs` imports** in service files — use the storage abstraction layer.
2. **All provider schemas validated** — do not guess flag names; verify against versioned docs
   or provider `--help` output.
3. **pnpm-lock.yaml** is generated by pnpm; do not reformat or hand-edit it.

Independent or cross-model review is optional. Run it only when the task,
configured governance policy, issue owner, or release owner explicitly requires
it.

---

## File locations quick-reference

| What              | Where                                                    |
| ----------------- | -------------------------------------------------------- |
| API routes        | `server/src/routes/`                                     |
| Services          | `server/src/services/`                                   |
| Zod schemas       | `server/src/schemas/`                                    |
| Storage           | `server/src/storage/`                                    |
| Server utilities  | `server/src/utils/`                                      |
| Provider adapters | `server/src/services/agent-provider-adapter-registry.ts` |
| React components  | `web/src/components/`                                    |
| Zustand stores    | `web/src/stores/`                                        |
| CLI commands      | `cli/src/commands/`                                      |
| Shared types      | `shared/src/`                                            |
| MCP server        | `mcp/src/`                                               |
| Prompt registry   | `prompt-registry/`                                       |
| SOPs              | `docs/SOP-*.md`                                          |
| Agent registry    | `.veritas-kanban/agent-registry.json`                    |
| Agent run logs    | `.veritas-kanban/logs/`                                  |
| Telemetry events  | `.veritas-kanban/telemetry/`                             |

---

## Harness instruction sources

| Harness            | Instruction source                                                     | Purpose                                             |
| ------------------ | ---------------------------------------------------------------------- | --------------------------------------------------- |
| Buzz Agent         | Veritas task envelope; repository files only if the runtime reads them | ACP task, worktree, tool, and completion contract   |
| Grok Build         | Veritas task envelope                                                  | ACP task, worktree, tool, and completion contract   |
| GitHub Copilot CLI | Veritas task envelope                                                  | ACP task, worktree, tool, and completion contract   |
| Codex / GPT        | `AGENTS.md` plus Veritas task envelope                                 | Canonical repository rules and managed-run contract |
| Claude Code        | `AGENTS.md`, `CLAUDE.md`, and Veritas task envelope                    | Canonical rules plus Claude-specific lessons        |
| Hermes             | `AGENTS.md` plus Veritas task envelope                                 | Hermes reads `AGENTS.md` from the worktree          |
| OpenClaw           | `AGENTS.md` plus the gateway task request                              | Canonical rules and server-owned gateway completion |