All policies

Contributing

How to propose a change to Vaelun, and the gates a change has to pass.

Contributing to Vaelun

Thanks for your interest. This document describes how to propose changes safely in a custody-sensitive codebase.

Ground rules

  • Never weaken a gate to make a feature "work." The raw spine gate, the

mainnet-only execution flag, and the smoke-surface gates exist for safety. If a change needs a gate flipped, that is a separate, explicit decision.

  • Honesty in docs is a requirement, not a style. Do not introduce

"production-ready", "parity", or "live private swap" claims (see docs/KNOWN_LIMITATIONS.md). Mark status as implemented / gated / experimental / deferred.

  • No secrets in code or tests. pnpm secrets:audit must pass.

Repository layout

This repository holds two independent pnpm projects, each with its own package.json and its own lockfile:

  • App/ — the product. Deploys to app.vaelun.xyz. Wallet, swaps, API routes,

database.

  • Web/ — the marketing site. Deploys to vaelun.xyz. Landing, docs, policies,

legal.

The repository root is not a Node project. There is no root package.json, so pnpm install and every pnpm <script> must be run from inside App/ or Web/. Running them at the root fails with ERR_PNPM_NO_PKG_MANIFEST.

Workflow

  • Open an issue describing the change and its risk surface.
  • Branch from main. Keep PRs focused.
  • Run the full local gate before pushing — in each project you touched, and

in both if your change spans them:

cd App
pnpm install
pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm secrets:audit
cd Web
pnpm install
pnpm lint && pnpm typecheck && pnpm test && pnpm check:docs-sync && pnpm build

Notes on the two that are not symmetric:

- pnpm secrets:audit exists only in App/ — Web/ has no database and no provider credentials to audit. - pnpm check:docs-sync exists only in Web/. The four root policy files (SECURITY.md, SUPPORT.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md) are mirrored into Web/content/, because Vercel builds Web/ as the project root and cannot read above it. If you edit one of those files at the root, copy it over or this check fails. - A production Web build needs no extra environment — just pnpm build. Web's redirects to the app are unconditional permanent hops; there is no migration mode to select.

  • Add or update tests. Security-relevant changes (auth, signing, solver proxy,

gating) require tests that exercise the *real* guard, not a mocked one — see server-side guards must read process.env directly, never client-only helpers (ADR-0005).

  • Update the relevant /docs page and add a changelog entry.

Code style

  • TypeScript, Biome for lint/format (pnpm lint, --write to fix).
  • Prefer zod validation over as casts of untrusted input.
  • Client/server boundary matters: never import a browser-only helper

(e.g. anything that checks typeof window) into a server route guard.

Commit / PR hygiene

  • Conventional, descriptive messages.
  • Reference the issue.
  • Note any gate, env var, or migration implications in the PR description.

Architecture decisions

Significant decisions are recorded as ADRs in docs/adr/. If your change alters an architectural invariant, add or supersede an ADR.