Contributing across axiom-orion

These are small, sharp, polyrepo pieces — each repo is its own deploy and its own toolchain. This file is the shared working agreement, written against the friction we actually hit, so we don't hit it again.

Why polyrepo (and not a monorepo)

The split is deliberate, not accidental:

• Deploy-aligned. governed-agents + cason-heritage → Vercel; agent-memory-service → Cloud Run; genealogy-graphrag → a library. Repo boundary = deploy boundary.
• Toolchain-aligned. Python, Next/TypeScript, and a zero-build static site don't share one tool sanely. cason-heritage is intentionally no-build (it runs faithful, dependency-free ports of the sibling layers for resilience on static hosting).
• Standalone. Each repo is a self-contained demonstration with its own README and eval.

The real coupling — the policy gate is hand-ported into cason-heritage "faithful to governed-agents" — is handled by a conformance test (below), not by merging repos.

Branches — short-lived, single-purpose, off main

The one rule that prevents the most pain:

• Branch off main, one PR per feature, delete after merge. Name it for the change: claude/<slug> or feat/<slug>.
• No long-lived, shared, cross-repo branch. A branch reused for everything and squash-merged piecemeal perpetually re-diverges from main and re-conflicts. (We learned this the hard way; it's retired.)
• Serialize work that touches the same file. Two branches both adding a card to LivingWorld.jsx will collide — and the resolution is almost always keep both, which means it should have been one branch. If you must parallelize, split the file first.
• Rebase on main before requesting review; resolve conflicts at the source, never by taking one side blind.

CI — every repo gates its own governance-relevant checks

A PR merges only when its repo's checks are green. Each repo owns its gate:

Repo	CI gate
governed-agents	typecheck (strict, no any) · verify-trace · verify-governance · offline demo smoke · the governed-trader example self-tests + eval
genealogy-graphrag	ruff · pytest · weight-attestation demo (S0) · Scribe OCR gate · fast eval
agent-memory-service	ruff · pytest (incl. PAG chain + serve contract)
cason-heritage	node selftests (selftest:all — governance · drift/H7 · BASIS · agents · …) · Playwright smoke · Vercel build

If a check exists but isn't wired into CI, it isn't a gate — wire it. (The node selftests were run by hand for a while; they now gate every cason-heritage PR.)

Truth-in-claims (the house style)

• A numeric claim is produced by an eval/self-test, not asserted in prose.
• Label what's provable / built, qualified, and aspirational — plainly, in the README and PR.
• Don't rename working code to sound novel; map vocabulary onto mechanisms (see the governance federation map).

Cross-repo contracts

The governance plane spans repos, so its contracts are pinned:

• The gate + TraceEvent contract is canonical in governed-agents (lib/governance.ts, lib/trace-events.ts). Every port (notably cason-heritage/ui_kits/living-line/governance.js) is verified against a shared contract fixture so "faithful port" is checked, not hoped.
• Provenance / attestation grades are stated at the grade actually obtained (none < declared < config-hash < behavioral < weight-fingerprint) — never inflated.

See docs/GOVERNANCE-FEDERATION.md for how the four repos compose, and cason-heritage/research/VORION-GOVERNANCE.md for the hardened architecture + the resolved decisions.