mirror of
https://github.com/PR0M3TH3AN/bitgate.git
synced 2026-10-27 08:31:00 +00:00
72 lines
3.1 KiB
Markdown
72 lines
3.1 KiB
Markdown
# 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.
|