andy
3de6e53ab0
Foundation for the persistent, inspectable cognitive runtime: README, implementation plan with phases and risk register, architecture, security model, threat model, contributing guide, eight ADRs covering the global workspace, event immutability, memory representation, LLM abstraction, capability system, authentication, frontend and storage. Includes Makefile, env example, compose stack (pgvector) and Dockerfile skeleton, plus a record of the development environment assumptions.
28 lines
1.7 KiB
Markdown
28 lines
1.7 KiB
Markdown
# Contributing to Noema
|
|
|
|
## Ground rules
|
|
|
|
- Read `PLAN.md`, `ARCHITECTURE.md` and `THREAT_MODEL.md` before changing cognitive or security code.
|
|
- Cognitive history is append-only. Never add code that updates or deletes rows in `cognitive_events`, `belief_versions`, `audit_log` or `personality_versions`.
|
|
- Every external action goes through `internal/capabilities`. No exceptions, no "internal" shortcuts.
|
|
- Every goroutine has an owner, a bound and a context. Use `internal/scheduler` worker pools; do not `go func()` in handlers.
|
|
- Deterministic first. If ordinary code can do it (scoring, policy, budgets, state transitions), the LLM does not.
|
|
- Treat all ingested data and all model output as hostile input (see `THREAT_MODEL.md`).
|
|
|
|
## Workflow
|
|
|
|
1. Small commits, imperative messages using the prefixes `feat:`, `fix:`, `docs:`, `test:`, `chore:`, `security:`, `refactor:`.
|
|
2. `make fmt lint test-race` must pass before committing. `make test-db` before finishing a phase.
|
|
3. Schema changes are numbered SQL files in `migrations/` with matching `.down.sql`. Never edit an applied migration.
|
|
4. Architectural decisions get an ADR in `docs/adr/` (copy `0000-template.md`).
|
|
5. Update `CHANGELOG.md` under Unreleased.
|
|
6. Never commit `.env`, keys or database dumps. `make security` runs gosec and govulncheck.
|
|
|
|
## Code style
|
|
|
|
Idiomatic Go, `context.Context` first, wrapped errors (`fmt.Errorf("...: %w", err)`), `log/slog`, no global mutable state, no panics for expected failures. Comments explain why, not what. Exported identifiers are documented.
|
|
|
|
## Tests
|
|
|
|
Unit tests live beside code. Tests needing PostgreSQL read `NOEMA_TEST_DATABASE_URL` and skip when it is unset. Scenario tests live in `tests/`.
|