Files

T

andy 3de6e53ab0 chore: initialise Noema repository

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.

2026-06-12 19:56:53 +01:00

1.7 KiB

Raw Permalink Blame History

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

Small commits, imperative messages using the prefixes feat:, fix:, docs:, test:, chore:, security:, refactor:.
make fmt lint test-race must pass before committing. make test-db before finishing a phase.
Schema changes are numbered SQL files in migrations/ with matching .down.sql. Never edit an applied migration.
Architectural decisions get an ADR in docs/adr/ (copy 0000-template.md).
Update CHANGELOG.md under Unreleased.
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/.