bitgate/AGENTS.md

AGENTS.md — BitGate (Nostr-Governance)

Purpose

BitGate is a headless governance SDK for Nostr apps: moderation and access control expressed as four decision dimensions (ranking, visibility, interaction, transaction). The engine carries no thresholds of its own — applications supply a policy definition; the engine supplies precedence, aggregation, composition, and explanation.

Repository map

• packages/ — npm workspaces: core (pure evaluation, zero deps), nostr (codecs), runtime, verify (signature verification), testing (conformance harness), widget, standalone, bitvid-compat, site.
• tests/ — unit, conformance, performance, and security test suites.
• examples/ — runnable integration examples (workspace members).
• fixtures/ — characterization corpus data.
• docs/ — security model, integration guide, NIPs, ADRs, TODO.
• scripts/ — corpus/fixture tooling and verify-no-reference-imports.mjs.

Build / test / validate

Requires Node >= 22. Install with npm ci (or npm install).

• Run npm test — unit tests plus conformance suite (vitest).
• Run npm run test:unit or npm run test:conformance for one half.
• Run npm run lint — reference-import check plus typechecking.
• Run npm run typecheck for types only.
• Run npm run build:types, npm run build:widget, npm run build:standalone, or npm run build for everything including the site.
• CI (.github/workflows/ci.yml) runs npm run lint, npm test, and npm run build:types on Node 22 — match that locally before pushing.

Conventions

• @bitgate/core stays dependency-free: no I/O, no browser globals. The verify package exists precisely so core never imports crypto.
• scripts/verify-no-reference-imports.mjs (part of lint) enforces import boundaries — do not work around it.
• ESM throughout ("type": "module"); TypeScript via JSDoc/.d.ts builds.

Backlog

Open work is tracked in docs/TODO.md.

Security

• Everything arriving from a relay is untrusted input; event.pubkey is an unauthenticated claim until a signature is verified. Administrative state fails closed without verifySignature. See docs/security.md before touching ingest, authorship, or verification paths.
• Never commit secrets or private keys; fixtures must contain only public, already-published event data.

Change policy

• Keep diffs minimal and scoped to the task.
• Behavior changes must update the corresponding tests (including conformance fixtures where applicable).
• Never weaken, skip, or delete tests to make a change pass.

Repo memory

Curated agent memory lives in .agents/ (index: .agents/MEMORY.md). Read it before substantive work — it holds the fails-closed verification and relays-are-untrusted conclusions with evidence refs into docs/security.md. Propose additions as files in .agents/proposals/; trusted memory under .agents/memory/ changes only through reviewed commits. Durable multi-session plans live under .agents/plans/ (the canonical backlog stays docs/TODO.md). Code, tests, and configuration always outrank memory.